Skip to main content
POST
/
api
/
v1
/
reservation
Create a new reservation
curl --request POST \
  --url https://api.example.com/api/v1/reservation \
  --header 'Content-Type: application/json' \
  --header 'x-calry-api-key: <api-key>' \
  --data '
{
  "listingID": "123e4567-e89b-12d3-a456-426614174000",
  "checkInDate": "2025-06-15T00:00:00.000Z",
  "checkOutDate": "2025-06-22T00:00:00.000Z",
  "guest": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890"
  },
  "guests": 2,
  "adults": 2,
  "notes": "Guest requested early check-in if possible",
  "source": "website",
  "totalBasePrice": 700,
  "totalFeePrice": 100,
  "totalTaxPrice": 80,
  "totalPrice": 880,
  "children": 1,
  "infants": 0,
  "pets": 0,
  "guestCountInfo": {
    "adults": 2,
    "children": 1,
    "infants": 0,
    "pets": 0
  },
  "currency": "USD",
  "commission": {
    "amount": 88,
    "description": "Platform Commission (10%)"
  },
  "promotionID": "123e4567-e89b-12d3-a456-426614174000",
  "reservationType": "INSTANT_BOOKING",
  "confirmationCode": "HMKYWB7BF8",
  "status": "accepted",
  "preferredLocale": "en",
  "checkInTime": 15,
  "checkOutTime": 11,
  "hostPayout": 750
}
'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "listingID": "123e4567-e89b-12d3-a456-426614174000",
  "integrationAccountID": "123e4567-e89b-12d3-a456-426614174000",
  "providerReservationID": "HMKYWB7BF8",
  "providerID": "3827197",
  "checkInDate": "2025-06-15",
  "checkOutDate": "2025-06-22",
  "guests": 2,
  "guest": {
    "id": "G12345",
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890"
  },
  "status": "CONFIRMED",
  "source": "website",
  "notes": "Guest requested early check-in if possible",
  "originalCurrency": "USD",
  "currency": "EUR",
  "totalPrice": 880,
  "components": {},
  "parentPropertyID": "PROP12345",
  "adults": 2,
  "children": 1,
  "infants": 0,
  "pets": 0,
  "createdAt": "2025-05-20T14:30:00.000Z",
  "updatedAt": "2025-05-21T10:15:00.000Z",
  "cancelledAt": "2025-05-25T09:45:00.000Z",
  "confirmedAt": "2025-05-20T15:00:00.000Z"
}

Authorizations

​
x-calry-api-key
string
header
required

Headers

​
x-calry-tenant-id
string

Optional tenant ID to specify which tenant to operate as. Controls which reservations are accessible. If not provided, the default tenant will be used.

Query Parameters

​
displayCurrency
string

Currency to display prices in (ISO 4217)

Example:

"USD"

Body

application/json

Reservation details

​
listingID
string
required

ID of the listing being reserved

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
checkInDate
string<date-time>
required

Check-in date for the reservation

Example:

"2025-06-15T00:00:00.000Z"

​
checkOutDate
string<date-time>
required

Check-out date for the reservation

Example:

"2025-06-22T00:00:00.000Z"

​
guest
object
required

Guest information

Example:
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "+1234567890"
}
​
guests
number
required

Total number of guests

Required range: x >= 1
Example:

2

​
adults
number
required

Number of adult guests

Required range: x >= 1
Example:

2

​
notes
string
required

Additional notes for the reservation

Example:

"Guest requested early check-in if possible"

​
source
string
required

Source of the reservation (e.g., website, agent)

Example:

"website"

​
totalBasePrice
number
required

Base price of the stay (without fees or taxes)

Example:

700

​
totalFeePrice
number
required

Total fees for the stay

Example:

100

​
totalTaxPrice
number
required

Total taxes for the stay

Example:

80

​
totalPrice
number
required

Total price of the stay (including base price, fees, and taxes)

Example:

880

​
children
number

Number of children

Required range: x >= 0
Example:

1

​
infants
number

Number of infants

Required range: x >= 0
Example:

0

​
pets
number

Number of pets

Required range: x >= 0
Example:

0

​
guestCountInfo
object

Guest count information

Example:
{
  "adults": 2,
  "children": 1,
  "infants": 0,
  "pets": 0
}
​
currency
string

Currency code for the reservation (ISO 4217)

Example:

"USD"

​
commission
object

Commission information for OTA reservations

​
promotionID
string

ID of any promotion applied to the reservation

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
reservationType
enum<string>
default:INSTANT_BOOKING

Type of reservation booking flow

Available options:
INSTANT_BOOKING,
PENDING_CONFIRMATION,
CONFIRMED
Example:

"INSTANT_BOOKING"

​
confirmationCode
string

Confirmation code for the reservation (used for Host.Tools integrations)

Example:

"HMKYWB7BF8"

​
status
enum<string>

Reservation status

Available options:
accepted,
pending,
cancelled,
inquiry
Example:

"accepted"

​
preferredLocale
object

Preferred locale for guest communication

Example:

"en"

​
checkInTime
number

Check-in time (hour of day, 0-23)

Required range: 0 <= x <= 23
Example:

15

​
checkOutTime
number

Check-out time (hour of day, 0-23)

Required range: 0 <= x <= 23
Example:

11

​
hostPayout
number

Host payout amount

Example:

750

Response

Reservation created successfully

​
id
string
required

Unique identifier for the reservation

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
listingID
string
required

ID of the listing being reserved

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
integrationAccountID
string
required

ID of the integration account

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
providerReservationID
string
required

Reservation ID in the provider system

Example:

"HMKYWB7BF8"

​
providerID
string
required

Provider identifier for listing

Example:

"3827197"

​
checkInDate
string
required

Check-in date (ISO format)

Example:

"2025-06-15"

​
checkOutDate
string
required

Check-out date (ISO format)

Example:

"2025-06-22"

​
guests
number
required

Total number of guests

Example:

2

​
guest
object
required

Guest information

​
status
enum<string>
required

Status of the reservation

Available options:
INQUIRY,
PENDING,
CONFIRMED,
MODIFIED,
MOVED,
CANCELLED,
EXPIRED,
NO_SHOW,
STAYING,
POST_STAY,
UNKNOWN,
BLOCKED
Example:

"CONFIRMED"

​
source
string
required

Source of the reservation

Example:

"website"

​
notes
string
required

Additional notes for the reservation

Example:

"Guest requested early check-in if possible"

​
originalCurrency
string
required

Original currency of the reservation (ISO 4217)

Example:

"USD"

​
currency
string
required

Display currency of the reservation (ISO 4217)

Example:

"EUR"

​
totalPrice
number
required

Total price of the stay

Example:

880

​
components
object
required

Price components breakdown

​
parentPropertyID
object

Parent property ID, if applicable

Example:

"PROP12345"

​
adults
number

Number of adult guests

Example:

2

​
children
number

Number of children

Example:

1

​
infants
number

Number of infants

Example:

0

​
pets
number

Number of pets

Example:

0

​
createdAt
string

Creation date of the reservation (ISO format)

Example:

"2025-05-20T14:30:00.000Z"

​
updatedAt
string

Last update date of the reservation (ISO format)

Example:

"2025-05-21T10:15:00.000Z"

​
cancelledAt
string

Cancellation date of the reservation (ISO format, if cancelled)

Example:

"2025-05-25T09:45:00.000Z"

​
confirmedAt
string

Confirmation date of the reservation (ISO format)

Example:

"2025-05-20T15:00:00.000Z"