Guides

Reservation migration

How to move your operations from Guesty's legacy reservation resources to the current ones for compliance.

Overview

Guesty has upgraded its reservations infrastructure. As part of that work, the reservation endpoints under /reservations are being replaced by a new set of endpoints. In this guide, you’ll find a full list of the old endpoints and their new equivalents.

New additions

The new API also supports things the old one could not, including:

Migration timeline

The legacy endpoints will be retired on 1 March 2027. After that date, calls to them will stop working.

Old and new reservation endpoints will run side by side until the close date, giving you time to update your integrations. One exception is the legacy guest payment resources: although they are marked for deprecation, we don't have a set removal date yet; however, we encourage you to adopt the new payment resources as soon as possible for the best experience.

Additional notes

Two things to know before you start:

  • One endpoint per operation. The single PUT /v1/reservations/{id} that accepted any field is replaced by a dedicated endpoint for each operation — dates, notes, status, and so on.
  • Related data by reference. Guest, financial, and payment data are no longer embedded in the response. You fetch them separately, so some flows that were one call may now require two or three requests.

The sections below address both changes.

Endpoint mapping

Reservation retrieval

The new reservation resources have leaner payloads and are more specific to each case. Financials and payments are now separate from stay details and have their own dedicated retrieval resources. Likewise, guest details must be pulled from the /guests endpoints.

  1. Get stay details:
    1. Deprecated: GET /reservations/{id} (link)
    2. Move to:
      1. GET /reservations-v3 (link)
      2. GET /reservations-v3/group/{groupId} (link)
  2. Get custom fields: Migrated earlier this year. See the Custom Reservation Fields Migration guide for details.
  3. Get the guest folio:
    1. Deprecated: GET /reservations/{id} (link)
    2. Move to: Supports up to 200 reservations per request.
      1. GET /guest-folio/overview (link)
      2. GET /guest-folio/invoice-items (link)
      3. GET /guest-folio/settings-snapshot (link)
  4. Get payments:
    1. Deprecated: GET /reservations/{id} (link)
    2. Move to:
      1. GET /payments (link)
        1. Supports one reservation per request only.
      2. GET /payments/{paymentId} (link)
        1. Supports one payment record per request only.
  5. Get reservation logs*:*
    1. Use: GET /reservation-logs/{reservationId} (link)
  6. Reservation report or curated search:
    1. Deprecated: GET /reservations (link)
    2. Move to:
      1. GET /reservations-v3/search (link)
        1. Filtering by guest name, phone, or email is not carried over—filter by guest ID instead. lastUpdatedAt date filtering is also not supported at this time. Rely on the reservation.updated.v2 webhook event for ordering and exact changes.
      2. GET /reservations-reports/{viewId} (link)
        1. Retrieves preconfigured reservation reports by their viewId

CSVs and Email reports

Some of the following operations are fully deprecated because they struggled with large datasets, and you can achieve the same outcome with newer, similar features.

  1. Download CSV reservation list:
    1. Deprecated: POST /reservations.csv (link)
    2. Move to: GET /reservations-reports/{viewId}/csv (link) or either GET /reservations-v3/search (link) or GET /reservations-reports/{viewId} (link) and transform the JSON data to a CSV on your end if necessary.
  2. Email a reservation list:
    1. Deprecated: POST /reservations.email (link)
    2. Move to: Schedule mailings of preconfigured reports through your Guesty dashboard. Learn more

Reservation creation

There are several booking types and flows, from quick booking to quote and book, to group bookings, and owner reservations:

  1. Create quote:
    1. Deprecated: POST /reservations (link)
    2. Move to:
      1. POST /quotes (link)
      2. POST /quotes/multiple (link)
  2. Apply coupon:
    1. Deprecated: POST /reservations (link)
    2. Move to: POST /quotes/{quoteId}/coupons (link)
  3. Quick booking: Applies the default rate plan and given fees
    1. Deprecated: POST /reservations (link)
    2. Move to: POST /reservations-v3 (link)
      1. Fees and taxes are applied after creation rather than in the create payload.
  4. Create booking from quote:
    1. Deprecated: PUT /reservations/{reservationId} (link)
      1. To simulate the quote and confirm flow, you would have had to confirm an inquiry or booking request.
    2. Migrate to: POST /reservations-v3/quote (link)
  5. Create group booking
    1. There is no legacy equivalent
    2. Use: POST /reservations-v3/group (link)
      1. Works in conjunction with POST /quotes/multiple (link)
  6. Approve/Decline booking request:
    1. Deprecated:
      1. POST /reservations/{id}/approve (link)
      2. POST /reservations/{id}/decline (link)
    2. Move to:
      1. POST /reservations-v3/{reservationId}/approve (link)
        1. Supports direct and OTA requests
      2. POST /reservations-v3/{reservationId}/decline (link)
        1. Optional reason and message supported
  7. Pre-approve channel inquiries:
    1. Deprecated: POST /reservations-api/reservations/{reservationId}/pre-approve (link)
    2. Move to: POST /reservations-v3/{reservationId}/pre-approve (link)
      1. The inquiry must be from a supporting channel like Airbnb and have an inquiry status
  8. Create owner reservation:
    1. Use: POST /reservations-v3/owner/confirmed (link)

Reservation alterations

Instead of a broad update resource, Guesty now uses a more focused approach with an endpoint for each operation type.

Approvals, stay details, and custom fields

  1. Change guest stay status:
    1. Deprecated: PUT /reservations/{reservationId} and body parameter guestStay (link)
    2. Move to: PUT /reservations-v3/guest-stay (link)
  2. Change reservation source:
    1. Deprecated: PUT /reservations/{reservationId} and body parameter source (link)
    2. Move to: PUT /reservations-v3/{reservationId}/source (link)
  3. Update reservation notes:
    1. Deprecated: PUT /reservations/{reservationId} and body parameters keyCode, notes, and specialRequests (link)
    2. Move to: PUT /reservations-v3/{reservationId}/notes (link)
  4. Update travel information:
    1. Deprecated: PUT /reservations/{reservationId} and body parameters travelInformation, transportation, reasonForVisit, and agentBooking (link)
    2. Move to: PUT /reservations-v3/{reservationId}/travel-information (link)
  5. Update reservation dates:
    1. Deprecated: PUT /reservations/{reservationId} and body parameters checkInDateLocalized, checkOutDateLocalized, plannedArrival, plannedDeparture, earlyCheckIn, and lateCheckOut (link)
    2. Move to: PUT /reservations-v3/{reservationId}/dates (link)
  6. Update reservation listing:
    1. Deprecated: PUT /reservations/{reservationId} and body parameter listingId (link)
    2. Migrate to: PUT /reservations-v3/{reservationId}/relocate (link)
  7. Update reservation status:
    1. Deprecated: PUT /reservations/{reservationId} and body parameter status (link)
    2. Move to: PUT /reservations-v3/{reservationId}/status (link)
  8. Update confirmation code:
    1. Deprecated: PUT /reservations/{reservationId} and body parameter confirmationCode (link)
    2. Move to: PUT /reservations-v3/{reservationId}/confirmation-code (link)
  9. Update booking date:
    1. Deprecated: PUT /reservations/{reservationId} and body parameter createdAt (link)
    2. Move to: PUT /reservations-v3/{reservationId}/booking-date (link)
      1. createdAt becomes canonical for Guesty as the date the booking enters our system, and bookingDate becomes the real-world adjustable booking date for when dates don’t align
  10. Update guests breakdown:
    1. Deprecated: PUT /reservations/{reservationId} and body parameters guestsCount and numberOfGuests (link)
    2. Move to: PUT /reservations-v3/{reservationId}/guests (link)
  11. Update reservation custom field:
    1. Deprecated: Migrated earlier this year. See the Custom Reservation Fields Migration guide for details.
    2. Move to: PUT /reservations-v3/{reservationId}/custom-fields (link)
  12. Delete reservation custom field:
    1. Deprecated: Migrated earlier this year. See the Custom Reservation Fields Migration guide for details.
    2. Move to: DELETE /reservations-v3/{reservationId}/custom-fields/{fieldId} (link)
  13. Create a mid-stay:
    1. No legacy equivalent. This is a new resource.
    2. Use: POST /reservations-v3/mid-stay (link)
  14. Request cancellation of a channel reservation:
  15. No legacy equivalent. This is a new resource.
  16. Use: POST /reservations-v3/{reservationId}/request-cancellation (link)
    1. The reservation must be from a channel and in confirmed status to be canceled
  17. Reservation comments: A new way to communicate internally about a guest stay. Only the comment author can edit and delete their comments. Learn more
    1. List comments: GET /reservations-v3/{reservationId}/comments
    2. Post a comment: POST /reservations-v3/{reservationId}/comments
    3. Edit a comment: PATCH /reservations-v3/{reservationId}/comments/{commentId}
    4. Delete a comment: DELETE /reservations-v3/{reservationId}/comments/{commentId}

Reservation financials

Access the reservation’s invoice and related financial information from the new dedicated endpoints. Price adjustment and adding an invoice item operations remain unchanged. Please continue to use their dedicated endpoints respectively.

  1. Guest folio and settings snapshot:
    1. Deprecated: GET /reservations/{reservationId}?fields=money (link)
    2. Move to:
      1. Guest folio overview: GET /guest-folio/overview
      2. Invoice item details: GET /guest-folio/invoice-items
      3. Settings snapshot: GET /guest-folio/settings-snapshot
  2. Add invoice item(s):
    1. Continue to use: POST /invoice-items/reservation/{reservationId} (link)
  3. Price adjustments:
    1. Continue to use:
      1. POST /price-adjustments/manual-total-amount (link)
      2. GET /price-adjustments/total-amount/{id} (link)
      3. GET /price-adjustments/adjustable-line-items/{reservationId} (link)

Reservation payments

Not all legacy reservation payment resources currently have a retirement date. However, we encourage you to adopt the new resources as soon as possible for the best experience.

Payment methods

  1. Retrieve payment methods:
    1. Legacy: GET /guests/{id}/payment-methods (link)
    2. Move to:
      1. GET /payment-methods (link)
      2. GET /payment-methods/{paymentMethodId} (link)
  2. Add a payment method:
    1. Legacy: POST /guests/{id}/payment-methods (link)
    2. Move to: POST /payment-methods (link)

Reservation payments

  1. Retrieve reservation payment records: Returns the totalPaid, balanceDue, and the payments.
    1. Legacy: GET /reservations/{reservationId}?fields=money.payments (link)
    2. Move to:
      1. GET /payments (link)
      2. GET /payments/{paymentId} (link)
  2. Create a payment:
    1. Deprecated: POST /reservations/{id}/payments (link)
    2. Move to:
      1. Schedule a charge: POST /payments
      2. Charge immediately: POST /payments/{paymentId}/pay
      3. Capture authorization hold: POST /payments/{paymentId}/capture
      4. Record chargeback: POST /payments/{paymentId}/chargeback
  3. Update payment:
    1. Deprecated: PUT reservations/{id}/payments/{paymentId} (link)
    2. Move to: PATCH /payments/{paymentId} (link)
  4. Cancel payment:
    1. Deprecated: PATCH /reservations/{id}/payments/{paymentId}/cancel (link)
    2. Move to: POST /payments/{paymentId}/cancel (link)
  5. Refund payment:
    1. Deprecated: POST /reservations/{id}/payments/{paymentId}/refund (link)
    2. Move to: POST /payments/{paymentId}/refund (link)

Recorded transactions

  1. Record offline payment:
    1. Deprecated: POST /reservations/{id}/payments (link)
    2. Move to:
      1. POST /payments/record (link)
      2. POST /payments/{paymentId}/record/refund (link)
  2. Update recorded payment
    1. Deprecated: PUT /reservations/{id}/payments/{paymentId} (link)
    2. Move to:
      1. PATCH /payments/{paymentId}/record (link)
      2. PATCH /payments/{paymentId}/record/refund/{refundId} (link)

Guest details

The new guest stay payload identifies the guest only by bookerId or guestId. You will need to call Get guest by ID to retrieve detailed information and Update guest to update the guest’s details.

Webhooks

Refer to the webhooks migration guide for complete details about the new webhook events you must subscribe to to ensure you receive the relevant updates across all bookings. New events to subscribe to include:

  • reservation.created.v2 and reservation.updated.v2
  • guest-folio.created and guest-folio.updated

The legacy reservation.new and reservation.updated events will also be retired on 1 March 2027.

Supplementary guides

We plan to update the existing reservation and payment guides in due course. Until then, please defer to this guide and the reference documentation and contact the Guesty Customer Experience team with any questions.

Need help?

Open a ticket with API support if you are unsure which endpoint replaces a flow you rely on, or if a replacement does not cover your use case.

Updated about 1 hour ago

Did this page help you?