Creating reservations

One endpoint books a stay wherever the listing's bookings live. A listing managed in a connected PMS is booked in that PMS; any other listing gets a direct booking. Quote it first, check what the listing supports, and change or cancel it through the same API.

Where the booking is made

The PMSs that take bookings this way are Mews, Cloudbeds, Hostaway, Guesty, Beds24, BookingSync, Lodgify, Smoobu, Hospitable, iGMS, OwnerRez and Track. What each one can do differs, and anything a PMS cannot do is refused with a clear error rather than faked — see PMS reservation support.

Check what a listing supports

GET /v1/listings/{id} returns capabilities.reservations: which writes the API will perform for that listing. A flag is true only when the PMS supports it, the workspace is still connected to the PMS, and the connection's write policy allows bookings through the API. Read it before you build a booking form, and use notes to explain to your user why something is off. GET /v1/connect/{provider} returns the same object for a whole PMS connection.

curl "https://api.repull.dev/v1/listings/4118" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

# "capabilities": {
#   "reservations": {
#     "managedBy": "pms",
#     "provider": "hostaway",
#     "create": true,
#     "modify": true,
#     "cancel": true,
#     "quote": true,
#     "customPrice": true,
#     "notes": "Direct-channel bookings: create (at a set total, or priced by Hostaway's calculator), quote, …",
#     "verifiedAgainst": "vendor_docs"
#   }
# }

Quote first

POST /v1/reservations/quote asks the PMS for the price and availability of a stay without booking anything. It is the same check a create makes when you send no totalPrice, so available: true with a total is what that create would charge — though the dates can still be taken in between.

curl -X POST "https://api.repull.dev/v1/reservations/quote" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "listingId": 4118, "checkIn": "2026-10-01", "checkOut": "2026-10-05", "adults": 2, "children": 1 }'

Bookable

{
  "listingId": "4118",
  "provider": "hostaway",
  "checkIn": "2026-10-01",
  "checkOut": "2026-10-05",
  "available": true,
  "total": 880,
  "currency": "USD",
  "breakdown": { "accommodation": 720, "cleaningFee": 100, "taxes": 60 },
  "restrictions": []
}

Not bookable as asked

available: false is an answer, not an error. The PMS's reasons are in restrictions, in its own words.

{
  "listingId": "4118",
  "provider": "guesty",
  "checkIn": "2026-10-01",
  "checkOut": "2026-10-02",
  "available": false,
  "total": null,
  "currency": null,
  "breakdown": null,
  "restrictions": ["Guesty: minimum stay is 3 nights"]
}

• A listing not managed in a PMS answers 422 pms_not_linked. Price it with GET /v1/quotes instead.
• Mews, Cloudbeds and iGMS have no quote API and answer 422 pms_write_unsupported. You can still book them; on iGMS a totalPrice is required.
• Hospitable quotes need an active Hospitable Direct plan.

Create the reservation

curl -X POST "https://api.repull.dev/v1/reservations" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c2f7e-4a3b-4f2e-9c8d-1b6a0e5d7c31" \
  -d '{
    "listingId": 4118,
    "checkIn": "2026-10-01",
    "checkOut": "2026-10-05",
    "guest": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "email": "ada@example.com",
      "phone": "+14035551234"
    },
    "adults": 2,
    "children": 1,
    "totalPrice": 880,
    "notes": "Late arrival, around 22:00.",
    "status": "confirmed",
    "sendConfirmationEmail": false
  }'

Request fields

Response — 201

{
  "id": "215708",
  "confirmationCode": "HA-4471923",
  "listingId": "4118",
  "platform": "direct",
  "status": "confirmed",
  "checkIn": "2026-10-01",
  "checkOut": "2026-10-05",
  "guestId": "91234",
  "totalPrice": 880,
  "currency": "USD",
  "unit": null,
  "pms": {
    "provider": "hostaway",
    "reservationId": "4471923",
    "applied": ["reservation"],
    "errors": [],
    "partial": false,
    "failedSections": []
  }
}

A direct booking

On a listing no PMS manages, send the direct-booking fields instead. There is no pms block in the response.

curl -X POST "https://api.repull.dev/v1/reservations" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3b8e0c52-1d7a-4b1e-a2f9-6c0d8e7f1a24" \
  -d '{
    "listingId": 4119,
    "checkIn": "2026-10-01",
    "checkOut": "2026-10-05",
    "guest": { "firstName": "Ada", "email": "ada@example.com" },
    "guestCount": 2,
    "checkInTime": "16:00",
    "currency": "USD"
  }'

Idempotency: send a key, and keep it

Always send an Idempotency-Key — a UUID generated where you build the booking. A network timeout on a booking is exactly the case it exists for. The key is also sent to the PMSas the booking's reference, so a retry that reaches the PMS a second time finds the booking instead of making another one.

When the booking exists only in the PMS

Rarely, the PMS takes the booking but its record cannot be read back in time. The answer is a 502 that is final: the booking exists in the PMS (existing names it), it arrives in Repull with the next sync, and reservation.created fires then.

{
  "error": {
    "code": "reservation_created_in_pms_only",
    "message": "Created in Lodgify (LG-88231) but its record could not be read here. It will arrive with the next sync.",
    "fix": "Do NOT retry. The booking exists in Lodgify (see `existing`) but could not be recorded in Repull yet; it arrives with the next sync and `reservation.created` fires then. Retrying with the same `Idempotency-Key` replays this answer.",
    "docs_url": "https://repull.dev/docs/errors/reservation_created_in_pms_only",
    "request_id": "req_01J5X7Y8Z9ABCDEF12345678",
    "provider": "lodgify",
    "existing": { "externalId": "88231", "confirmationCode": "LG-88231" },
    "pms": { "applied": ["reservation"], "errors": [] },
    "retryable": false
  }
}

Partial success

A booking is made in steps: the reservation itself, then follow-ups such as notes or a tentative state. When the reservation was created but a follow-up did not apply, the answer is still 201, with pms.partial: true and the steps in pms.failedSections. The booking exists — do not create it again. Fix the missing part in the PMS, or tell your user what did not apply.

{
  "id": "215709",
  "confirmationCode": "SM-1290031",
  "listingId": "4120",
  "status": "confirmed",
  "totalPrice": 640,
  "currency": "EUR",
  "pms": {
    "provider": "smoobu",
    "reservationId": "1290031",
    "applied": ["reservation"],
    "errors": [{ "section": "notes", "code": "rejected", "message": "Smoobu: notice too long" }],
    "partial": true,
    "failedSections": [{ "section": "notes", "code": "rejected", "message": "Smoobu: notice too long" }]
  }
}

Changing and cancelling

Changes and cancellations follow the booking to where it lives. A stay managed in a PMS is changed in the PMS first, then Repull's copy is refreshed from the PMS's record — changing only Repull's copy would be undone by the next sync. Both endpoints return the PMS's outcome as pms.

curl -X PATCH "https://api.repull.dev/v1/reservations/215708" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d2c9a10-8e4f-4c3b-9a71-2f6e0b8d4c55" \
  -d '{ "checkIn": "2026-10-02", "checkOut": "2026-10-06", "guestCount": 3 }'

• On a PMS stay, checkIn, checkOut and guestCount are changed. Moving it to another listing and changing arrival or departure times are done in the PMS (422 pms_write_unsupported), as is anything the PMS's API cannot change — dates on Smoobu, for example.
• The PMS checks availability: taken dates answer 409 pms_unavailable.
• Several PMSs keep the booked total when the dates change (Hostaway, Beds24, BookingSync, iGMS, Hospitable); OwnerRez does not recalculate charges either. Adjust the price in the PMS if it should change.
• Guest details, pricing, status, platform and notes are refused by name with 422 unsupported_field. See Update a reservation.

curl -X POST "https://api.repull.dev/v1/reservations/215708/cancel" \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7a3f1e92-0c5b-4d8e-b6a4-9e2d1c0f8b37" \
  -d '{ "reason": "Guest changed plans" }'

• A PMS booking is cancelled in the PMS, then read back. No cancellation fee is charged.
• Lodgify declines the booking rather than deleting it.
• OwnerRez's API cannot cancel: 422 pms_write_unsupported — cancel it in OwnerRez.
• Direct, website and owner bookings are cancelled in Repull, releasing the nights.
• Cancelling a booking that is already cancelled returns alreadyCancelled: true, not an error.
• A channel booking — including one relayed through a PMS — answers 409 reservation_owned_by_channel. So does a change; group bookings in the PMS answer 409 pms_group_booking.

See Cancel a reservation for channel bookings. However a booking is changed — here, in the PMS, or on a channel — reservation.updated and reservation.cancelled fire when the change reaches Repull.

Each PMS at a glance

Constraints and the access each PMS needs are on PMS reservation support. Mews and Cloudbeds were run end to end on their vendors' sandboxes; every other PMS is verified against the vendor's API documentation.

Errors

Every error carries fix and docs_url, plus provider when a PMS is involved. Switch on code.