Create a reservation

Updated:

POST/property/{connection_id}/reservation

Creates a PropertyReservation. Provide the unified PropertyReservation fields in the request body; they are mapped to the provider's API. Returns the created PropertyReservation.

Parameters

fieldsstring array
Fields to return
rawstring
Raw parameters to include in the 3rd-party request. Encoded as a URL component. eg. raw parameters: foo=bar&zoo=bar -> raw=foo%3Dbar%26zoo%3Dbar
connection_idstring required
ID of the connection

Payload

idstring
unique identifier for the reservation
created_atdate-time
when the reservation was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atdate-time
when the reservation was last updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
listing_idstring
pointer to the Property Listing that is booked
unittype_idsstring array
Property Unittypes (room types) that are booked
guest_idstring
pointer to the Property Guest who made the reservation
guest_namestring
the primary guest full name
guest_emailstring
the primary guest email address
guest_phonestring
the primary guest telephone number
status enum
Valid values:
"INQUIRY"
"PENDING"
"CONFIRMED"
"CANCELLED"
"CHECKED_IN"
the reservation status
sourcestring
the booking channel, eg. Airbnb, Booking.com or direct
confirmation_codestring
the booking channel confirmation code
start_atdate-time
the arrival (check-in) date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
end_atdate-time
the departure (check-out) date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
estimated_arrival_timestring
the guest estimated arrival time (HH:mm, local time)
estimated_departure_timestring
the guest estimated departure time (HH:mm, local time)
nightsnumber
number of nights
guestsnumber
total number of guests
adultsnumber
number of adults
childrennumber
number of children
infantsnumber
number of infants
petsnumber
number of pets
currencystring
ISO 4217 currency code
total_amountnumber
the total price of the reservation
paid_amountnumber
the amount already paid
balance_amountnumber
the remaining balance
line_items array
price breakdown (base price, fees, taxes, discounts)
notesstring
free-text notes about the reservation
cancelled_atdate-time
when the reservation was cancelled (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
web_urlstring
the reservation URL
metadata array
custom field values

Returns

Response fieldTypeRequiredDescription
idstringNounique identifier for the reservation
created_atstring (date-time)Nowhen the reservation was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)Nowhen the reservation was last updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
listing_idstringNopointer to the Property Listing that is booked
unittype_idsstring[]NoProperty Unittypes (room types) that are booked
guest_idstringNopointer to the Property Guest who made the reservation
guest_namestringNothe primary guest full name
guest_emailstringNothe primary guest email address
guest_phonestringNothe primary guest telephone number
statusenumNothe reservation status Values: INQUIRY, PENDING, CONFIRMED, CANCELLED, CHECKED_IN, CHECKED_OUT, NO_SHOW, OTHER
sourcestringNothe booking channel, eg. Airbnb, Booking.com or direct
confirmation_codestringNothe booking channel confirmation code
start_atstring (date-time)Nothe arrival (check-in) date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
end_atstring (date-time)Nothe departure (check-out) date (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
estimated_arrival_timestringNothe guest estimated arrival time (HH:mm, local time)
estimated_departure_timestringNothe guest estimated departure time (HH:mm, local time)
nightsnumberNonumber of nights
guestsnumberNototal number of guests
adultsnumberNonumber of adults
childrennumberNonumber of children
infantsnumberNonumber of infants
petsnumberNonumber of pets
currencystringNoISO 4217 currency code
total_amountnumberNothe total price of the reservation
paid_amountnumberNothe amount already paid
balance_amountnumberNothe remaining balance
line_itemsPropertyLineitem[]Noprice breakdown (base price, fees, taxes, discounts)
line_items[].typeenumNobase price, fee, tax, discount or deposit Values: BASE, FEE, TAX, DISCOUNT, DEPOSIT, OTHER
line_items[].namestringNothe line item name, eg. Cleaning fee
line_items[].descriptionstringNofree-text description of the line item
line_items[].amountnumberNothe line item amount (discounts are negative)
line_items[].is_mandatorybooleanNowhether the line item is mandatory
notesstringNofree-text notes about the reservation
cancelled_atstring (date-time)Nowhen the reservation was cancelled (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
web_urlstringNothe reservation URL
metadataPropertyMetadata[]Nocustom field values
metadata[].idstringNothe custom field identifier
metadata[].slugstringNothe custom field key
metadata[].valueobjectNothe custom field value
metadata[].namespacestringNothe scope or origin of the custom field
metadata[].formatenumNothe data type of the value Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
metadata[].extra_dataobjectNoadditional data about the custom field

Errors

Errors return the HTTP status code and a JSON body with statusCode, error (the short label) and message (a human-readable detail).

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many requests to unified.to API; max requests per minute: N"
}
StatusErrorMeaning
400Bad RequestThe request was malformed or failed validation.
401UnauthorizedThe connection is likely broken; re-authorize it.
403ForbiddenThe connection is missing permissions or scopes.
404Not FoundThe requested resource does not exist.
429Too Many RequestsRate limit exceeded (see the two sources below).
500Internal Server ErrorAn unexpected error occurred.
501Not ImplementedNot supported by this integration.

Errors from the underlying integration pass through: the integration's status comes back as ours (429, 401, 403, 404 or 5xx), usually with its message. When the integration's error body is unclear, Unified extracts what it can and returns a clearer message.

429 Too Many Requests

A 429 has two possible sources:

  • The integration's own rate limit, passed through.
  • Unified's workspace limit: a rolling 60 seconds, set by plan, with the message Too many requests to unified.to API; max requests per minute: N.
const options = {
  method: 'POST',
  url: 'https://api.unified.to/property/5de520f96e439b002043d8dc/reservation',
  headers: {
    authorization: 'bearer .....'
  },
  data: undefined,
  params: {
    fields: '',
    raw: '',
  }
};

const results = await axios.request(options);
Are we missing anything? Let us know
Was this page helpful?