Bookings

Overview

This resource represents the Bookings (reservations) occupying the calendar for a given Rental.

Depending on the use case, there are various types of Bookings (determined by status attribute):

Booked - the actual confirmed bookings for a given Client.
Tentative - the bookings that are not confirmed yet. Either these bookings eventually become Booked or they expire (which is determined by tentative_expires_at attribute) and are canceled in such such case.
Unavailable - mostly useful for blocking the calendar (e.g. for a given season)
Canceled - the bookings that no longer occupy the calendar

start_at and end_at are naive datetimes

start_at and end_at are naive datetimes denominated in the rental's local timezone. They are serialized with a trailing Z, but that Z is misleading and should be ignored — the values are not UTC. The wire format is a historical quirk and changing it would be a breaking change for existing integrations, so we don't plan to change it. If you need an absolute moment in time (for example, to compare against now in a time-window check), use start_at_global / end_at_global instead, which are true UTC instants.

Parameters

OAuth Scopes:
public
bookings_write_owned
bookings_read
bookings_write

Name	Type	Read/Write	Description
id	Integer	Read	Booking's id.
reference	String	Read	Booking's reference code.
status	String	Read	Booking's status.
updated_at	Time	Read	Booking's update time.
start_at	Time	Read	Booking's start time as a naive datetime in the rental's timezone (see warning above).
start_at_global	Time	Read	Booking's start time as a true UTC instant. Prefer this for absolute time-window comparisons.
end_at	Time	Read	Booking's end time as a naive datetime in the rental's timezone (see warning above).
end_at_global	Time	Read	Booking's end time as a true UTC instant. Prefer this for absolute time-window comparisons.

Name	Type	Read/Write	Description	Constraints
account	Integer	Read	Account's ID related to the Booking
rental	Integer	Read	Rental's ID related to the Booking
client	Integer	Read	Client's ID related to the Booking
rental_agreement	Integer	Read	RentalAgreement's ID related to the Bookings Fee
source	Integer	Read	Source's ID related to the Booking
inquiry	Integer	Read	Inquiry's ID related to the Booking
created_by_id	Integer	Read	Created By's ID related to the Booking	(User, Booking or Application - this is a polymorphic association)
created_by_type	String	Read	Created By's Type related to the Booking	(User, Booking or Application - this is a polymorphic association)
booking_comments	Array	Read	Array of related Bookings Comments IDs
booking_fees	Array	Read	Array of related Bookings Fees IDs
booking_taxes	Array	Read	Array of related Bookings Taxes IDs
booking_payments	Array	Read	Array of related Bookings Payments IDs
conversations	Array	Read	Array of related Inbox Conversation IDs
payments	Array	Read	Array of related Payments IDs
rentals_tags	Array	Read	Array of related Rentals Tags IDs
bookings_tags	Array	Read	Array of related Bookings Tags IDs
internal_fees	Array	Read	Array containing details of fees collected by Smily from a booking, list of fee kinds described in enums section
id	Integer	Read	Booking's id.
client_id	Integer	Write	Client id related to the Booking.
source_id	Integer	Write	Source id related to the Booking.
bookings_tag_ids	Array	Write	Array of ids of BookingsTags to be associated with Booking. Replaces all existing tags.	Cannot be used together with `bookings_tag_ids_to_add` or `bookings_tag_ids_to_remove`
bookings_tag_ids_to_add	Array	Write	Array of ids of BookingsTags to add to the Booking. Preserves existing tags.	Cannot be used together with `bookings_tag_ids`
bookings_tag_ids_to_remove	Array	Write	Array of ids of BookingsTags to remove from the Booking.	Cannot be used together with `bookings_tag_ids`
adults	Integer	Read/Write	Booking's number of adults.
booked	Boolean	Read/Write	Booking's booked status, false by default. When set to true, marks a regular booking.
channel_price	Integer	Read/Write	Price accepted by the traveler on the channel site, excluding traveler's fees (eg: Airbnb).
children	Integer	Read/Write	Booking's number of children.
commission	Decimal	Write	Booking's commission fee.	Requires `final_price` to be present
currency	String	Read/Write	Booking's currency code, list of codes described in enums section.	Must be blank or included in currencies list
damage_deposit	Decimal	Read/Write	Booking's damage deposit.	greater than or equal to: 0. It is read-only and auto-generated in case `damage_deposit_collection_method` is `"smily_damage_deposit_with_swikly"`
charge_damage_deposit_on_arrival	Boolean	Read/Write	Defines if charge damage deposit will be charged on arrival.	Can be `true` or `false` for Pro subscriptions, only `false` allowed for Service subscriptions when `damage_deposit_collection_method` is `"smily_damage_deposit_with_swikly"`, and only `true` allowed for Service subsriptions when `damage_deposit_collection_method` is `"with_smily"`
damage_deposit_collection_method	String	Read/Write	Booking's damage deposit collection method.	List of values described in enums section.
damage_deposit_external_collection_method_name	String	Read/Write	Damage deposit collection method name (in case `damage_deposit_collection_method` is `"external"`).	Leave blank unless `damage_deposit_collection_method` is `"external"`
discount	String	Read/Write	Booking's discount. (in percents e.g. 10%)	must blank or an absolute value (e.g. 100) or percentage value (e.g. 10%)
door_key_code	String	Read/Write	Booking's rental door key code.
downpayment	Decimal	Read/Write	Booking's downpayment.	Requires `final_price` to be present
expected_checkin_time	String	Read/Write	Expected guest's checkin time.	must be blank or represent a time value (e.g. 12, 12:30)
expected_checkout_time	String	Read/Write	Expected guest's checkout time.	must be blank or represent a time value (e.g. 12, 12:30)
final_payback_to_owner	Decimal	Read/Write	Final payback to rental owner.	Must be lower than `final_price`
final_price	Decimal	Read/Write	Booking's final price. (after discount)
initial_price	Decimal	Read/Write	Booking's initial price.
payment_left_to_collect	Decimal	Read	Booking's payment left to collect.
locked	String	Write	Booking's locked status.
notes	Text	Read/Write	Booking's notes. (1000 characters max)	maximum length: 6000
reference	String	Read	Booking's reference code.
rental_payback_to_owner	Decimal	Read/Write	Amount of money to pay back to owner (only rental, excluding fees).	Must be blank or greater than or equal to: 0 and lower than `initial_price`
status	String	Read	Booking's status.
unavailable	Boolean	Read/Write	Booking's unavailable status, false by default. When set to true, marks the given period as unavailable. Commonly used for closed or maintenance periods.
external_reference	String	Read/Write	Booking's reference from the source channel.
cancelation_reason	String	Read/Write	Booking's cancelation reason (for writable part - it can be used in both update and cancelation endpoints)
cancelation_message_to_guest	String	Read/Write	Booking's cancelation message to guest (for writable part - only in cancelation endpoint)
cancelation_message_to_channel	String	Read/Write	Booking's cancelation message to guest (for writable part - only in cancelation endpoint)
imported	Boolean	Read/Write	Whether this booking was imported from the external Channel or not
reconciliation	Decimal	Read/Write	Booking's reconciliation
authorized_amount	Decimal	Read	Booking's authorized amount
paid_or_authorized_amount	Decimal	Read	Booking's paid or authorized amount
updated_at	Time	Read	Booking's update time.
start_at	Time	Read/Write	Booking's start time as a naive datetime in the rental's timezone (see warning above).	Required, must be before `end_at`
start_at_global	Time	Read	Booking's start time as a true UTC instant. Prefer this for absolute time-window comparisons.
end_at	Time	Read/Write	Booking's end time as a naive datetime in the rental's timezone (see warning above).	Required, must be after `start_at`
end_at_global	Time	Read	Booking's end time as a true UTC instant. Prefer this for absolute time-window comparisons.
canceled_at	Time	Write	Booking's cancel time.
tentative_expires_at	Time	Write	Booking's tentative expiry time, null by default. When set, it will mark the period as "on hold" until the given date. Once this date is passed, the period will automatically become available again.	Must be in the future
booked_at	Time	Write	Exact timestamp when a booking was booked

Name	Type	Read/Write	Description
account	Integer	Read	Account's ID related to the Booking
rental	Integer	Read	Rental's ID related to the Booking
client	Integer	Read	Client's ID related to the Booking
rental_agreement	Integer	Read	RentalAgreement's ID related to the Bookings Fee
source	Integer	Read	Source's ID related to the Booking
inquiry	Integer	Read	Inquiry's ID related to the Booking
created_by_id	Integer	Read	Created By's ID related to the Booking
created_by_type	String	Read	Created By's Type related to the Booking
booking_comments	Array	Read	Array of related Bookings Comments IDs
booking_fees	Array	Read	Array of related Bookings Fees IDs
booking_taxes	Array	Read	Array of related Bookings Taxes IDs
booking_payments	Array	Read	Array of related Bookings Payments IDs
conversations	Array	Read	Array of related Inbox Conversation IDs
payments	Array	Read	Array of related Payments IDs
rentals_tags	Array	Read	Array of related Rentals Tags IDs
bookings_tags	Array	Read	Array of related Bookings Tags IDs
internal_fees	Array	Read	Array containing details of fees collected by Smily from a booking, list of fee kinds described in enums section
discount_code_usage	Integer	Read	Discount Code Usage ID related to the Booking
id	Integer	Read	Booking's id.
adults	Integer	Read	Booking's number of adults.
booked	Boolean	Read	Booking's booked status, false by default. When set to true, marks a regular booking.
bookings_payments_count	Integer	Read	Booking's number of payments.
channel_price	Integer	Read	Price accepted by the traveler on the channel site, excluding traveler's fees (eg: Airbnb).
children	Integer	Read	Booking's number of children.
commission	Decimal	Read	Booking's commission fee.
currency	String	Read	Booking's currency code, list of codes described in enums section.
damage_deposit	Decimal	Read	Booking's damage deposit.
charge_damage_deposit_on_arrival	Boolean	Read	Defines if charge damage deposit will be charged on arrival. Can be `true` or `false` for Pro subscriptions, only `false` allowed for Service subscriptions when `damage_deposit_collection_method` is `"smily_damage_deposit_with_swikly"`, and only `true` allowed for Service subsriptions when `damage_deposit_collection_method` is `"with_smily"`
damage_deposit_collection_method	String	Read	Booking's damage deposit collection method. List of values described in enums section.
damage_deposit_external_collection_method_name	String	Read	Damage deposit collection method name (in case `damage_deposit_collection_method` is `"external"`). Can be blank unless `damage_deposit_collection_method` is `"external"`
discount	String	Read	Booking's discount. (in percents e.g. 10%)
door_key_code	String	Read	Booking's rental door key code.
downpayment	Decimal	Read	Booking's downpayment.
expected_checkin_time	String	Read	Expected guest's checkin time.
expected_checkout_time	String	Read	Expected guest's checkout time.
final_payback_to_owner	Decimal	Read	Final payback to rental owner.
final_price	Decimal	Read	Booking's final price. (after discount)
final_rental_price	Decimal	Read	initial_rental_price reduced by discount (taxes and fees not included).
initial_price	Decimal	Read	Booking's initial price.
initial_rental_price	Decimal	Read	An alias for initial_price
payment_left_to_collect	Decimal	Read	Booking's payment left to collect.
locked	String	Read	Booking's locked status.
notes	Text	Read	Booking's notes.
owned_by_app	Boolean	Read	Defines whether booking was created by current app.
paid_amount	Decimal	Read	Booking's amount that have already been paid.
payment_url	String	Read	Url for booking's payment.
short_payment_url	String	Read	Shortened url for booking's payment.
reference	String	Read	Booking's reference code.
rental_payback_to_owner	Decimal	Read	Amount of money to pay back to owner (only rental, excluding fees).
review_requests_count	Integer	Read	Booking's number of review requests.
status	String	Read	Booking's status.
unavailable	Boolean	Read	Booking's unavailable status, false by default. When set to true, marks the given period as unavailable. Commonly used for closed or maintenance periods.
external_reference	String	Read	Booking's reference from the source channel.
cancelation_reason	String	Read	Booking's cancelation reason
cancelation_initiator	String	Read	Booking's cancelation initiator. Can be `null`
cancelation_message_to_guest	String	Read	Booking's cancelation message to guest
cancelation_message_to_channel	String	Read	Booking's cancelation message to guest
imported	Boolean	Read/Write	Whether this booking was imported from the external Channel or not
reconciliation	Decimal	Read	Booking's reconciliation
authorized_amount	Decimal	Read	Booking's authorized amount
paid_or_authorized_amount	Decimal	Read	Booking's paid or authorized amount
balance_due_at	Time	Read	Booking's payment deadline.
created_at	Time	Read	Booking's create time.
updated_at	Time	Read	Booking's update time.
start_at	Time	Read	Booking's start time as a naive datetime in the rental's timezone (see warning above).
start_at_global	Time	Read	Booking's start time as a true UTC instant. Prefer this for absolute time-window comparisons.
end_at	Time	Read	Booking's end time as a naive datetime in the rental's timezone (see warning above).
end_at_global	Time	Read	Booking's end time as a true UTC instant. Prefer this for absolute time-window comparisons.
canceled_at	Time	Read	Booking's cancel time.
tentative_expires_at	Time	Read	Booking's tentative expiry time, null by default. When set, it will mark the period as "on hold" until the given date. Once this date is passed, the period will automatically become available again.
contract_updated_at	Time	Read	Booking's contract update time.
booking_rent_revenue_amount	Decimal	Read	Booking's rent revenue amount (rental price component only).
city_taxes_amount	Decimal	Read	Booking's city taxes amount.

Name	Type	Read/Write	Description	Constraints
account	Integer	Read	Account's ID related to the Booking
rental	Integer	Read	Rental's ID related to the Booking
client	Integer	Read	Client's ID related to the Booking
rental_agreement	Integer	Read	RentalAgreement's ID related to the Bookings Fee
source	Integer	Read	Source's ID related to the Booking
inquiry	Integer	Read	Inquiry's ID related to the Booking
created_by_id	Integer	Read	Created By's ID related to the Booking	(User, Booking or Application - this is a polymorphic association)
created_by_type	String	Read	Created By's Type related to the Booking	(User, Booking or Application - this is a polymorphic association)
booking_comments	Array	Read	Array of related Bookings Comments IDs
booking_fees	Array	Read	Array of related Bookings Fees IDs
booking_taxes	Array	Read	Array of related Bookings Taxes IDs
booking_payments	Array	Read	Array of related Bookings Payments IDs
conversations	Array	Read	Array of related Inbox Conversation IDs
payments	Array	Read	Array of related Payments IDs
rentals_tags	Array	Read	Array of related Rentals Tags IDs
bookings_tags	Array	Read	Array of related Bookings Tags IDs
internal_fees	Array	Read	Array containing details of fees collected by Smily from a booking, list of fee kinds described in enums section
discount_code_usage	Integer	Read	Discount Code Usage ID related to the Booking
id	Integer	Read	Booking's id.
client_id	Integer	Write	Client id related to the Booking.
source_id	Integer	Write	Source id related to the Booking.
bookings_tag_ids	Array	Write	Array of ids of BookingsTags to be associated with Booking. Replaces all existing tags.	Cannot be used together with `bookings_tag_ids_to_add` or `bookings_tag_ids_to_remove`
bookings_tag_ids_to_add	Array	Write	Array of ids of BookingsTags to add to the Booking. Preserves existing tags.	Cannot be used together with `bookings_tag_ids`
bookings_tag_ids_to_remove	Array	Write	Array of ids of BookingsTags to remove from the Booking.	Cannot be used together with `bookings_tag_ids`
adults	Integer	Read/Write	Booking's number of adults.
booked	Boolean	Read/Write	Booking's booked status, false by default. When set to true, marks a regular booking.
bookings_payments_count	Integer	Read	Booking's number of payments.
channel_price	Integer	Read/Write	Price accepted by the traveler on the channel site, excluding traveler's fees (eg: Airbnb).
children	Integer	Read/Write	Booking's number of children.
commission	Decimal	Read/Write	Booking's commission fee.	Requires `final_price` to be present
currency	String	Read/Write	Booking's currency code, list of codes described in enums section.	Must be blank or included in currencies list
damage_deposit	Decimal	Read/Write	Booking's damage deposit.	greater than or equal to: 0. It is read-only and auto-generated in case `damage_deposit_collection_method` is `"smily_damage_deposit_with_swikly"`
charge_damage_deposit_on_arrival	Boolean	Read/Write	Defines if charge damage deposit will be charged on arrival.	Can be `true` or `false` for Pro subscriptions, only `false` allowed for Service subscriptions when `damage_deposit_collection_method` is `"smily_damage_deposit_with_swikly"`, and only `true` allowed for Service subsriptions when `damage_deposit_collection_method` is `"with_smily"`
damage_deposit_collection_method	String	Read/Write	Booking's damage deposit collection method.	List of values described in enums section.
damage_deposit_external_collection_method_name	String	Read/Write	Damage deposit collection method name (in case `damage_deposit_collection_method` is `"external"`).	Leave blank unless `damage_deposit_collection_method` is `"external"`
discount	String	Read/Write	Booking's discount. (in percents e.g. 10%)	must blank or an absolute value (e.g. 100) or percentage value (e.g. 10%)
door_key_code	String	Read/Write	Booking's rental door key code.
downpayment	Decimal	Read/Write	Booking's downpayment.	Requires `final_price` to be present
expected_checkin_time	String	Read/Write	Expected guest's checkin time.	must be blank or represent a time value (e.g. 12, 12:30)
expected_checkout_time	String	Read/Write	Expected guest's checkout time.	must be blank or represent a time value (e.g. 12, 12:30)
checkin_type	String	Read/Write	Chosen checkin method	List of values described in enums section
final_payback_to_owner	Decimal	Read/Write	Final payback to rental owner.	Must be lower than `final_price`
final_price	Decimal	Read/Write	Booking's final price. (after discount)
final_rental_price	Decimal	Read	initial_rental_price reduced by discount (taxes and fees not included).
initial_price	Decimal	Read/Write	Booking's initial price.
initial_rental_price	Decimal	Read	An alias for initial_price.
payment_left_to_collect	Decimal	Read	Booking's payment left to collect.
locked	String	Read/Write	Booking's locked status.
notes	Text	Read/Write	Booking's notes. (1000 characters max)	maximum length: 6000
owned_by_app	Boolean	Read	Defines whether booking was created by current app.
paid_amount	Decimal	Read	Booking's amount that have already been paid.
payment_url	String	Read	Url for booking's payment.
short_payment_url	String	Read	Shortened url for booking's payment.
reference	String	Read	Booking's reference code.
rental_payback_to_owner	Decimal	Read/Write	Amount of money to pay back to owner (only rental, excluding fees).	Must be blank or greater than or equal to: 0 and lower than `initial_price`
review_requests_count	Integer	Read	Booking's number of review requests.
status	String	Read	Booking's status.
unavailable	Boolean	Read/Write	Booking's unavailable status, false by default. When set to true, marks the given period as unavailable. Commonly used for closed or maintenance periods.
external_reference	String	Read/Write	Booking's reference from the source channel.
cancelation_reason	String	Read/Write	Booking's cancelation reason (for writable part - it can be used in both update and cancelation endpoints)
cancelation_initiator	String	Read/Write	Booking's cancelation initiator	Must be one of the cancelation initiators or `null`
cancelation_message_to_guest	String	Read/Write	Booking's cancelation message to guest (for writable part - only in cancelation endpoint)
cancelation_message_to_channel	String	Read/Write	Booking's cancelation message to guest (for writable part - only in cancelation endpoint)
imported	Boolean	Read/Write	Whether this booking was imported from the external Channel or not
reconciliation	Decimal	Read/Write	Booking's reconciliation
authorized_amount	Decimal	Read	Booking's authorized amount
paid_or_authorized_amount	Decimal	Read	Booking's paid or authorized amount
balance_due_at	Time	Read	Booking's payment deadline.
created_at	Time	Read	Booking's create time.
updated_at	Time	Read	Booking's update time.
start_at	Time	Read/Write	Required. Booking's start time as a naive datetime in the rental's timezone (see warning above).
start_at_global	Time	Read	Booking's start time as a true UTC instant. Prefer this for absolute time-window comparisons.
end_at	Time	Read/Write	Required. Booking's end time as a naive datetime in the rental's timezone (see warning above).
end_at_global	Time	Read	Booking's end time as a true UTC instant. Prefer this for absolute time-window comparisons.
canceled_at	Time	Read/Write	Booking's cancel time.
tentative_expires_at	Time	Read/Write	Booking's tentative expiry time, null by default. When set, it will mark the period as "on hold" until the given date. Once this date is passed, the period will automatically become available again.
contract_updated_at	Time	Read	Booking's contract update time.
booked_at	Time	Write	Exact timestamp when a booking was booked
booking_rent_revenue_amount	Decimal	Read	Booking's rent revenue amount (rental price component only).
city_taxes_amount	Decimal	Read	Booking's city taxes amount.

List bookings

Based on the OAuth token scopes bookings listing will be limited to a certain range.

Scope	Read Permissions
`:public`	Display only future, not canceled bookings
`:bookings_write_owned`	Display only future, not canceled bookings
`:bookings_read`	Display all bookings
`:bookings_write`	Display all bookings

Returns a list of all bookings for current account(s).

Returns only future and non-canceled bookings by default

By default this endpoint returns only future and non-canceled bookings, if you like to change this behavior, make sure to check the search parameters.

GET /bookings

OAuth Scopes:
public / bookings_write_owned
bookings_read / bookings_write

response.json
{
  "links": {
    "bookings.account": "https://www.bookingsync.com/api/v3/accounts/{bookings.account}",
    "bookings.rental": "https://www.bookingsync.com/api/v3/rentals/{bookings.rental}",
    "bookings.bookings_tags": "https://www.bookingsync.com/api/v3/bookings_tags/{bookings.bookings_tags}",
    "bookings.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{bookings.rentals_tags}",
    "bookings.discount_code_usage": "https://www.bookingsync.com/api/v3/discount_code_usages/{bookings.discount_code_usage}"
  },
  "bookings": [
    {
      "links": {
        "account": 1,
        "rental": 16,
        "bookings_tags": [
          1,
          2
        ],
        "rentals_tags": [],
        "discount_code_usage": 12
      },
      "id": 203,
      "start_at": "2026-05-27T12:59:44Z",
      "end_at": "2026-06-03T12:59:44Z",
      "status": "Booked",
      "updated_at": "2026-05-13T12:59:44.733Z"
    }
  ],
  "meta": {}
}

response.json
{
  "links": {
    "bookings.account": "https://www.bookingsync.com/api/v3/accounts/{bookings.account}",
    "bookings.rental": "https://www.bookingsync.com/api/v3/rentals/{bookings.rental}",
    "bookings.client": "https://www.bookingsync.com/api/v3/clients/{bookings.client}",
    "bookings.rental_agreement": "https://www.bookingsync.com/api/v3/rental_agreements/{bookings.rental_agreement}",
    "bookings.source": "https://www.bookingsync.com/api/v3/sources/{bookings.source}",
    "bookings.inquiry": "https://www.bookingsync.com/api/v3/inquiries/{bookings.inquiry}",
    "bookings.booking_comments": "https://www.bookingsync.com/api/v3/booking_comments/{bookings.booking_comments}",
    "bookings.bookings_fees": "https://www.bookingsync.com/api/v3/bookings_fees/{bookings.bookings_fees}",
    "bookings.bookings_taxes": "https://www.bookingsync.com/api/v3/bookings_taxes/{bookings.bookings_taxes}",
    "bookings.payments": "https://www.bookingsync.com/api/v3/payments/{bookings.payments}",
    "bookings.bookings_payments": "https://www.bookingsync.com/api/v3/bookings_payments/{bookings.bookings_payments}",
    "bookings.bookings_tags": "https://www.bookingsync.com/api/v3/bookings_tags/{bookings.bookings_tags}",
    "bookings.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{bookings.rentals_tags}",
    "bookings.discount_code_usage": "https://www.bookingsync.com/api/v3/discount_code_usages/{bookings.discount_code_usage}"
  },
  "bookings": [
    {
      "links": {
        "account": 1,
        "rental": 16,
        "client": 37,
        "inquiry": null,
        "rental_agreement": null,
        "source": null,
        "bookings_fees": [],
        "bookings_payments": [
          23
        ],
        "bookings_taxes": [],
        "bookings_tags": [
          1,
          2
        ],
        "booking_comments": [],
        "conversations": [
          11
        ],
        "payments": [
          23
        ],
        "rentals_tags": [],
        "discount_code_usage": 12
      },
      "id": 80,
      "created_by_id": 42,
      "created_by_type": "User",
      "start_at": "2026-05-27T12:59:44Z",
      "end_at": "2026-06-03T12:59:44Z",
      "status": "Booked",
      "updated_at": "2026-05-13T12:59:44.735Z",
      "reference": "0000EG",
      "booked_at": "BOOKED_AT",
      "booked": true,
      "unavailable": false,
      "tentative_expires_at": null,
      "initial_price": "3000.0",
      "initial_rental_price": "3000.0",
      "channel_price": null,
      "discount": "10%",
      "final_price": "2700.0",
      "final_rental_price": "2700.0",
      "downpayment": null,
      "paid_amount": "2700.0",
      "authorized_amount": "0.0",
      "paid_or_authorized_amount": "2700.0",
      "currency": "USD",
      "notes": "",
      "damage_deposit": "0.0",
      "charge_damage_deposit_on_arrival": true,
      "adults": 5,
      "children": null,
      "bookings_payments_count": 1,
      "review_requests_count": 0,
      "locked": null,
      "created_at": "2026-05-06T12:59:44.735Z",
      "canceled_at": null,
      "cancelation_reason": null,
      "cancelation_initiator": null,
      "cancelation_message_to_guest": null,
      "cancelation_message_to_channel": null,
      "expected_checkin_time": "14:45",
      "expected_checkout_time": "11:30",
      "checkin_type": "lockbox",
      "payment_url": null,
      "short_payment_url": null,
      "balance_due_at": "2026-05-20T12:59:44Z",
      "rental_payback_to_owner": null,
      "final_payback_to_owner": "0.0",
      "commission": null,
      "contract_updated_at": "2026-05-11T12:59:44Z",
      "external_reference": null,
      "owned_by_app": false,
      "payment_left_to_collect": "0.0",
      "booking_rent_revenue_amount": "3000.0",
      "city_taxes_amount": "0.0",
      "internal_fees": [
        {
          "kind": "traveller_fee",
          "net_amount_in_cents": 3429,
          "gross_amount_in_cents": 4115,
          "currency": "EUR",
          "vat_percentage": 20
        },
        {
          "kind": "cancelation_protection_fee",
          "net_amount_in_cents": 10000,
          "gross_amount_in_cents": 12000,
          "currency": "EUR",
          "vat_percentage": 20
        }
      ]
    }
  ],
  "meta": {}
}

Search bookings

Search parameters allow to filter bookings by specified fields.

Example:

GET /bookings?status=booked,unavailable&from=2014-03-24T12:00:00Z

Search Parameters

Name	Type	Default	Description
from	Time	now	Bookings ending after given time. Default is now.
until	Time		Bookings starting before given time.
months	Integer		Bookings starting before `:from` + `:months`.
status	String		List of comma separated statuses. Possible values: booked,unavailable,tentative.
include_canceled	Boolean	false	Show also canceled bookings (requires `:bookings_read` or `:bookings_write` scope).
rental_id	String		List of comma separated IDs. Returns only bookings for this rental(s)
client_id	String		List of comma separated IDs. Returns only bookings for this client(s)
updated_since	Time		Bookings updated after given time. Also includes ids of bookings canceled after given time.

Get a single booking

Returns a single booking identified by ID

GET /bookings/:booking_id

OAuth Scopes:
public / bookings_write_owned
bookings_read / bookings_write

response.json
{
  "links": {
    "bookings.account": "https://www.bookingsync.com/api/v3/accounts/{bookings.account}",
    "bookings.rental": "https://www.bookingsync.com/api/v3/rentals/{bookings.rental}",
    "bookings.bookings_tags": "https://www.bookingsync.com/api/v3/bookings_tags/{bookings.bookings_tags}",
    "bookings.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{bookings.rentals_tags}",
    "bookings.discount_code_usage": "https://www.bookingsync.com/api/v3/discount_code_usages/{bookings.discount_code_usage}"
  },
  "bookings": [
    {
      "links": {
        "account": 1,
        "rental": 16,
        "bookings_tags": [
          1,
          2
        ],
        "rentals_tags": [],
        "discount_code_usage": 12
      },
      "id": 203,
      "start_at": "2026-05-27T12:59:44Z",
      "end_at": "2026-06-03T12:59:44Z",
      "status": "Booked",
      "updated_at": "2026-05-13T12:59:44.742Z"
    }
  ],
  "meta": {}
}

response.json
{
  "links": {
    "bookings.account": "https://www.bookingsync.com/api/v3/accounts/{bookings.account}",
    "bookings.rental": "https://www.bookingsync.com/api/v3/rentals/{bookings.rental}",
    "bookings.client": "https://www.bookingsync.com/api/v3/clients/{bookings.client}",
    "bookings.rental_agreement": "https://www.bookingsync.com/api/v3/rental_agreements/{bookings.rental_agreement}",
    "bookings.source": "https://www.bookingsync.com/api/v3/sources/{bookings.source}",
    "bookings.inquiry": "https://www.bookingsync.com/api/v3/inquiries/{bookings.inquiry}",
    "bookings.booking_comments": "https://www.bookingsync.com/api/v3/booking_comments/{bookings.booking_comments}",
    "bookings.bookings_fees": "https://www.bookingsync.com/api/v3/bookings_fees/{bookings.bookings_fees}",
    "bookings.bookings_taxes": "https://www.bookingsync.com/api/v3/bookings_taxes/{bookings.bookings_taxes}",
    "bookings.payments": "https://www.bookingsync.com/api/v3/payments/{bookings.payments}",
    "bookings.bookings_payments": "https://www.bookingsync.com/api/v3/bookings_payments/{bookings.bookings_payments}",
    "bookings.bookings_tags": "https://www.bookingsync.com/api/v3/bookings_tags/{bookings.bookings_tags}",
    "bookings.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{bookings.rentals_tags}",
    "bookings.discount_code_usage": "https://www.bookingsync.com/api/v3/discount_code_usages/{bookings.discount_code_usage}"
  },
  "bookings": [
    {
      "links": {
        "account": 1,
        "rental": 16,
        "client": 37,
        "inquiry": null,
        "rental_agreement": null,
        "source": null,
        "bookings_fees": [],
        "bookings_payments": [
          23
        ],
        "bookings_taxes": [],
        "bookings_tags": [
          1,
          2
        ],
        "booking_comments": [],
        "conversations": [
          11
        ],
        "payments": [
          23
        ],
        "rentals_tags": [],
        "discount_code_usage": 12
      },
      "id": 80,
      "created_by_id": 42,
      "created_by_type": "User",
      "start_at": "2026-05-27T12:59:44Z",
      "end_at": "2026-06-03T12:59:44Z",
      "status": "Booked",
      "updated_at": "2026-05-13T12:59:44.745Z",
      "reference": "0000EG",
      "booked_at": "BOOKED_AT",
      "booked": true,
      "unavailable": false,
      "tentative_expires_at": null,
      "initial_price": "3000.0",
      "initial_rental_price": "3000.0",
      "channel_price": null,
      "discount": "10%",
      "final_price": "2700.0",
      "final_rental_price": "2700.0",
      "downpayment": null,
      "paid_amount": "2700.0",
      "authorized_amount": "0.0",
      "paid_or_authorized_amount": "2700.0",
      "currency": "USD",
      "notes": "",
      "damage_deposit": "0.0",
      "charge_damage_deposit_on_arrival": true,
      "adults": 5,
      "children": null,
      "bookings_payments_count": 1,
      "review_requests_count": 0,
      "locked": null,
      "created_at": "2026-05-06T12:59:44.745Z",
      "canceled_at": null,
      "cancelation_reason": null,
      "cancelation_initiator": null,
      "cancelation_message_to_guest": null,
      "cancelation_message_to_channel": null,
      "expected_checkin_time": "14:45",
      "expected_checkout_time": "11:30",
      "checkin_type": "lockbox",
      "payment_url": null,
      "short_payment_url": null,
      "balance_due_at": "2026-05-20T12:59:44Z",
      "rental_payback_to_owner": null,
      "final_payback_to_owner": "0.0",
      "commission": null,
      "contract_updated_at": "2026-05-11T12:59:44Z",
      "external_reference": null,
      "owned_by_app": false,
      "payment_left_to_collect": "0.0",
      "booking_rent_revenue_amount": "3000.0",
      "city_taxes_amount": "0.0",
      "internal_fees": [
        {
          "kind": "traveller_fee",
          "net_amount_in_cents": 3429,
          "gross_amount_in_cents": 4115,
          "currency": "EUR",
          "vat_percentage": 20
        },
        {
          "kind": "cancelation_protection_fee",
          "net_amount_in_cents": 10000,
          "gross_amount_in_cents": 12000,
          "currency": "EUR",
          "vat_percentage": 20
        }
      ]
    }
  ],
  "meta": {}
}

Create a new booking

Status assignment

To assign a status to a booking, you have to set either booked, unavailable or tentative_expires_at fields. Only one of those attributes can be used at the same time.

start_at and end_at must include a time component

Send start_at and end_at as full ISO-8601 datetimes (e.g. 2026-06-15T16:00:00Z), not bare dates. The recommended values are the rental's checkin_time for start_at and checkout_time for end_at — those are the times at which the previous/next guest is expected to leave/arrive, so they avoid overlap with adjacent bookings. A date-only value is coerced to midnight in the rental's local timezone, which typically falls inside an adjacent booking's stay and is rejected with start_at/end_at "is within a used period" — even when /rentals/search reported availability (search works at day granularity).

Creates a booking for given rental.

POST /rentals/:rental_id/bookings

OAuth Scopes:
bookings_write_owned
bookings_write

request.json
{
  "bookings": [
    {
      "booked": true,
      "client_id": 37,
      "adults": 5,
      "currency": "USD",
      "discount": "10%",
      "final_price": "2700.0",
      "initial_price": "3000.0",
      "start_at": "2026-06-15T16:00:00Z",
      "end_at": "2026-06-22T10:00:00Z",
      "bookings_tag_ids": [
        1,
        2
      ]
    }
  ]
}

response.json
{
  "links": {
    "bookings.account": "https://www.bookingsync.com/api/v3/accounts/{bookings.account}",
    "bookings.rental": "https://www.bookingsync.com/api/v3/rentals/{bookings.rental}",
    "bookings.client": "https://www.bookingsync.com/api/v3/clients/{bookings.client}",
    "bookings.rental_agreement": "https://www.bookingsync.com/api/v3/rental_agreements/{bookings.rental_agreement}",
    "bookings.source": "https://www.bookingsync.com/api/v3/sources/{bookings.source}",
    "bookings.inquiry": "https://www.bookingsync.com/api/v3/inquiries/{bookings.inquiry}",
    "bookings.booking_comments": "https://www.bookingsync.com/api/v3/booking_comments/{bookings.booking_comments}",
    "bookings.bookings_fees": "https://www.bookingsync.com/api/v3/bookings_fees/{bookings.bookings_fees}",
    "bookings.bookings_taxes": "https://www.bookingsync.com/api/v3/bookings_taxes/{bookings.bookings_taxes}",
    "bookings.payments": "https://www.bookingsync.com/api/v3/payments/{bookings.payments}",
    "bookings.bookings_payments": "https://www.bookingsync.com/api/v3/bookings_payments/{bookings.bookings_payments}",
    "bookings.bookings_tags": "https://www.bookingsync.com/api/v3/bookings_tags/{bookings.bookings_tags}",
    "bookings.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{bookings.rentals_tags}",
    "bookings.discount_code_usage": "https://www.bookingsync.com/api/v3/discount_code_usages/{bookings.discount_code_usage}"
  },
  "bookings": [
    {
      "links": {
        "account": 1,
        "rental": 16,
        "client": 37,
        "inquiry": null,
        "rental_agreement": null,
        "source": null,
        "bookings_fees": [],
        "bookings_payments": [
          23
        ],
        "bookings_taxes": [],
        "bookings_tags": [
          1,
          2
        ],
        "booking_comments": [],
        "conversations": [
          11
        ],
        "payments": [
          23
        ],
        "rentals_tags": [],
        "discount_code_usage": 12
      },
      "id": 80,
      "created_by_id": 42,
      "created_by_type": "User",
      "start_at": "2026-05-27T12:59:44Z",
      "end_at": "2026-06-03T12:59:44Z",
      "status": "Booked",
      "updated_at": "2026-05-13T12:59:44.759Z",
      "reference": "0000EG",
      "booked_at": "BOOKED_AT",
      "booked": true,
      "unavailable": false,
      "tentative_expires_at": null,
      "initial_price": "3000.0",
      "initial_rental_price": "3000.0",
      "channel_price": null,
      "discount": "10%",
      "final_price": "2700.0",
      "final_rental_price": "2700.0",
      "downpayment": null,
      "paid_amount": "2700.0",
      "authorized_amount": "0.0",
      "paid_or_authorized_amount": "2700.0",
      "currency": "USD",
      "notes": "",
      "damage_deposit": "0.0",
      "charge_damage_deposit_on_arrival": true,
      "adults": 5,
      "children": null,
      "bookings_payments_count": 1,
      "review_requests_count": 0,
      "locked": null,
      "created_at": "2026-05-06T12:59:44.759Z",
      "canceled_at": null,
      "cancelation_reason": null,
      "cancelation_initiator": null,
      "cancelation_message_to_guest": null,
      "cancelation_message_to_channel": null,
      "expected_checkin_time": "14:45",
      "expected_checkout_time": "11:30",
      "checkin_type": "lockbox",
      "payment_url": null,
      "short_payment_url": null,
      "balance_due_at": "2026-05-20T12:59:44Z",
      "rental_payback_to_owner": null,
      "final_payback_to_owner": "0.0",
      "commission": null,
      "contract_updated_at": "2026-05-11T12:59:44Z",
      "external_reference": null,
      "owned_by_app": false,
      "payment_left_to_collect": "0.0",
      "booking_rent_revenue_amount": "3000.0",
      "city_taxes_amount": "0.0",
      "internal_fees": [
        {
          "kind": "traveller_fee",
          "net_amount_in_cents": 3429,
          "gross_amount_in_cents": 4115,
          "currency": "EUR",
          "vat_percentage": 20
        },
        {
          "kind": "cancelation_protection_fee",
          "net_amount_in_cents": 10000,
          "gross_amount_in_cents": 12000,
          "currency": "EUR",
          "vat_percentage": 20
        }
      ]
    }
  ],
  "meta": {}
}

request.json
{
  "bookings": [
    {
      "booked": true,
      "client_id": 37,
      "adults": 5,
      "currency": "USD",
      "discount": "10%",
      "final_price": "2700.0",
      "initial_price": "3000.0",
      "start_at": "2026-06-15T16:00:00Z",
      "end_at": "2026-06-22T10:00:00Z",
      "bookings_tag_ids": [
        1,
        2
      ]
    }
  ]
}

response.json
{
  "links": {
    "bookings.account": "https://www.bookingsync.com/api/v3/accounts/{bookings.account}",
    "bookings.rental": "https://www.bookingsync.com/api/v3/rentals/{bookings.rental}",
    "bookings.client": "https://www.bookingsync.com/api/v3/clients/{bookings.client}",
    "bookings.rental_agreement": "https://www.bookingsync.com/api/v3/rental_agreements/{bookings.rental_agreement}",
    "bookings.source": "https://www.bookingsync.com/api/v3/sources/{bookings.source}",
    "bookings.inquiry": "https://www.bookingsync.com/api/v3/inquiries/{bookings.inquiry}",
    "bookings.booking_comments": "https://www.bookingsync.com/api/v3/booking_comments/{bookings.booking_comments}",
    "bookings.bookings_fees": "https://www.bookingsync.com/api/v3/bookings_fees/{bookings.bookings_fees}",
    "bookings.bookings_taxes": "https://www.bookingsync.com/api/v3/bookings_taxes/{bookings.bookings_taxes}",
    "bookings.payments": "https://www.bookingsync.com/api/v3/payments/{bookings.payments}",
    "bookings.bookings_payments": "https://www.bookingsync.com/api/v3/bookings_payments/{bookings.bookings_payments}",
    "bookings.bookings_tags": "https://www.bookingsync.com/api/v3/bookings_tags/{bookings.bookings_tags}",
    "bookings.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{bookings.rentals_tags}",
    "bookings.discount_code_usage": "https://www.bookingsync.com/api/v3/discount_code_usages/{bookings.discount_code_usage}"
  },
  "bookings": [
    {
      "links": {
        "account": 1,
        "rental": 16,
        "client": 37,
        "inquiry": null,
        "rental_agreement": null,
        "source": null,
        "bookings_fees": [],
        "bookings_payments": [
          23
        ],
        "bookings_taxes": [],
        "bookings_tags": [
          1,
          2
        ],
        "booking_comments": [],
        "conversations": [
          11
        ],
        "payments": [
          23
        ],
        "rentals_tags": [],
        "discount_code_usage": 12
      },
      "id": 80,
      "created_by_id": 42,
      "created_by_type": "User",
      "start_at": "2026-05-27T12:59:44Z",
      "end_at": "2026-06-03T12:59:44Z",
      "status": "Booked",
      "updated_at": "2026-05-13T12:59:44.771Z",
      "reference": "0000EG",
      "booked_at": "BOOKED_AT",
      "booked": true,
      "unavailable": false,
      "tentative_expires_at": null,
      "initial_price": "3000.0",
      "initial_rental_price": "3000.0",
      "channel_price": null,
      "discount": "10%",
      "final_price": "2700.0",
      "final_rental_price": "2700.0",
      "downpayment": null,
      "paid_amount": "2700.0",
      "authorized_amount": "0.0",
      "paid_or_authorized_amount": "2700.0",
      "currency": "USD",
      "notes": "",
      "damage_deposit": "0.0",
      "charge_damage_deposit_on_arrival": true,
      "adults": 5,
      "children": null,
      "bookings_payments_count": 1,
      "review_requests_count": 0,
      "locked": null,
      "created_at": "2026-05-06T12:59:44.771Z",
      "canceled_at": null,
      "cancelation_reason": null,
      "cancelation_initiator": null,
      "cancelation_message_to_guest": null,
      "cancelation_message_to_channel": null,
      "expected_checkin_time": "14:45",
      "expected_checkout_time": "11:30",
      "checkin_type": "lockbox",
      "payment_url": null,
      "short_payment_url": null,
      "balance_due_at": "2026-05-20T12:59:44Z",
      "rental_payback_to_owner": null,
      "final_payback_to_owner": "0.0",
      "commission": null,
      "contract_updated_at": "2026-05-11T12:59:44Z",
      "external_reference": null,
      "owned_by_app": false,
      "payment_left_to_collect": "0.0",
      "booking_rent_revenue_amount": "3000.0",
      "city_taxes_amount": "0.0",
      "internal_fees": [
        {
          "kind": "traveller_fee",
          "net_amount_in_cents": 3429,
          "gross_amount_in_cents": 4115,
          "currency": "EUR",
          "vat_percentage": 20
        },
        {
          "kind": "cancelation_protection_fee",
          "net_amount_in_cents": 10000,
          "gross_amount_in_cents": 12000,
          "currency": "EUR",
          "vat_percentage": 20
        }
      ]
    }
  ],
  "meta": {}
}

Comments, Fees and Taxes

You can also pass comments, bookings fees and bookings taxes directly during a booking creation using the parameters: comments, bookings_fees and bookings_taxes.

Managing Bookings Tags

There are three ways to manage bookings tags on a booking:

bookings_tag_ids - Replaces all existing tags with the provided list. Use this when you want to set the exact list of tags.
bookings_tag_ids_to_add - Adds tags to the existing ones without removing any. Use this for incremental additions.
bookings_tag_ids_to_remove - Removes specific tags while preserving others. Use this for selective removal.

You can use bookings_tag_ids_to_add and bookings_tag_ids_to_remove together in the same request to add and remove tags simultaneously. However, neither can be used together with bookings_tag_ids.

Update a booking

Returns an updated booking identified by ID.

PUT /bookings/:booking_id

OAuth Scopes:
bookings_write_owned
bookings_write

request.json
{
  "bookings": [
    {
      "booked": true,
      "client_id": 37,
      "adults": 5,
      "currency": "USD",
      "discount": "10%",
      "final_price": "2700.0",
      "initial_price": "3000.0",
      "start_at": "2026-06-15T16:00:00Z",
      "end_at": "2026-06-22T10:00:00Z"
    }
  ]
}

response.json
{
  "links": {
    "bookings.account": "https://www.bookingsync.com/api/v3/accounts/{bookings.account}",
    "bookings.rental": "https://www.bookingsync.com/api/v3/rentals/{bookings.rental}",
    "bookings.bookings_tags": "https://www.bookingsync.com/api/v3/bookings_tags/{bookings.bookings_tags}",
    "bookings.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{bookings.rentals_tags}",
    "bookings.discount_code_usage": "https://www.bookingsync.com/api/v3/discount_code_usages/{bookings.discount_code_usage}"
  },
  "bookings": [
    {
      "links": {
        "account": 1,
        "rental": 16,
        "bookings_tags": [
          1,
          2
        ],
        "rentals_tags": [],
        "discount_code_usage": 12
      },
      "id": 203,
      "start_at": "2026-05-27T12:59:44Z",
      "end_at": "2026-06-03T12:59:44Z",
      "status": "Booked",
      "updated_at": "2026-05-13T12:59:44.787Z"
    }
  ],
  "meta": {}
}

request.json
{
  "bookings": [
    {
      "booked": true,
      "client_id": 37,
      "adults": 5,
      "currency": "USD",
      "discount": "10%",
      "final_price": "2700.0",
      "initial_price": "3000.0",
      "start_at": "2026-06-15T16:00:00Z",
      "end_at": "2026-06-22T10:00:00Z"
    }
  ]
}

response.json
{
  "links": {
    "bookings.account": "https://www.bookingsync.com/api/v3/accounts/{bookings.account}",
    "bookings.rental": "https://www.bookingsync.com/api/v3/rentals/{bookings.rental}",
    "bookings.bookings_tags": "https://www.bookingsync.com/api/v3/bookings_tags/{bookings.bookings_tags}",
    "bookings.rentals_tags": "https://www.bookingsync.com/api/v3/rentals_tags/{bookings.rentals_tags}",
    "bookings.discount_code_usage": "https://www.bookingsync.com/api/v3/discount_code_usages/{bookings.discount_code_usage}"
  },
  "bookings": [
    {
      "links": {
        "account": 1,
        "rental": 16,
        "bookings_tags": [
          1,
          2
        ],
        "rentals_tags": [],
        "discount_code_usage": 12
      },
      "id": 203,
      "start_at": "2026-05-27T12:59:44Z",
      "end_at": "2026-06-03T12:59:44Z",
      "status": "Booked",
      "updated_at": "2026-05-13T12:59:44.789Z"
    }
  ],
  "meta": {}
}

Cancel a booking

Required OAuth scope: :bookings_write or :bookings_write_owned

Returns an empty response with 204 No Content status code on success.

DELETE /bookings/:booking_id

Overview​

Parameters​

List bookings​

Search bookings​

Search Parameters​

Get a single booking​

Create a new booking​

Update a booking​

Cancel a booking​