Hotel Stay Tools

Manage hotel stay records — accommodation bookings with check-in/check-out dates, room counts, and associated CO₂e emissions. This is Scope 3 Category 6 (business travel) data.

`list_hotel_stays`

List hotel stay records with optional filters. Parameters:

Parameter	Type	Required	Default	Description
`organization_id`	string	No	default org	Organization UUID
`status`	string	No	—	Status filter: `active`, `deleted`
`start_date`	string	No	—	Filter stays from this date (YYYY-MM-DD)
`end_date`	string	No	—	Filter stays until this date (YYYY-MM-DD)
`name`	string	No	—	Filter by hotel name (partial match)
`page`	integer	No	1	Page number
`size`	integer	No	50	Results per page

Example response:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Team offsite — Madrid",
      "check_in_date": "2024-11-04",
      "check_out_date": "2024-11-07",
      "country": "ES",
      "address": "Gran Vía 28, Madrid, Spain",
      "hotel_name": "Hotel Gran Vía",
      "rooms": 3,
      "status": "active",
      "source": "manual",
      "co2e": 18.54,
      "file_id": null,
      "file_name": null,
      "created_at": "2024-11-01T09:00:00Z",
      "updated_at": "2024-11-01T09:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "pages": 1
}

Key response fields:

Field	Description
`name`	Description or label for the stay (e.g. “Team offsite — Madrid”)
`hotel_name`	Name of the hotel
`check_in_date` / `check_out_date`	Stay dates (number of nights = difference between these)
`rooms`	Number of rooms booked
`country`	ISO country code of the hotel location
`co2e`	Calculated CO₂e emissions in kg
`source`	How the record was created: `manual`, `bulk_upload`, or `api`

Example prompts:

"List our hotel stays for Q1 2024"
"Show hotel stays at Marriott properties"
"How many hotel nights did we book last year?"
"What are the emissions from our hotel stays in 2025?"

Write Operations

`create_hotel_stay`

Create a hotel stay record for Scope 3 accommodation emissions. CO₂e is calculated based on the country and number of nights — the response will initially show co2e as null. Duration can be specified in two ways:

Provide check_out_date directly.
Provide nights — the check-out date is calculated as check_in_date + nights.

At least one of these must be given. Parameters:

Parameter	Type	Required	Default	Description
`check_in_date`	string	Yes	—	Check-in date (`YYYY-MM-DD`)
`country`	string	Yes	—	ISO-2 country code of the hotel (e.g. `"ES"`, `"FR"`, `"US"`)
`check_out_date`	string	No	—	Check-out date (`YYYY-MM-DD`), must be on or after `check_in_date`
`nights`	integer	No	—	Number of nights (alternative to `check_out_date`, min 1)
`rooms`	integer	No	1	Number of rooms booked (max 10,000)
`name`	string	No	—	Guest or trip name for identification
`hotel_name`	string	No	—	Name of the hotel
`address`	string	No	—	Hotel address (used for geocoding)
`organization_id`	string	No	default org	Organization UUID

You can provide either check_out_date or nights — the backend calculates the other. If both are omitted, the API returns a validation error.

CO₂e emissions are calculated in the background after creation. The initial response will show co2e: null. Call list_hotel_stays after a few seconds to see the calculated value.

Example response:

{
  "id": "550e8400-...",
  "check_in_date": "2025-06-01",
  "check_out_date": "2025-06-04",
  "country": "ES",
  "hotel_name": "Hotel Gran Vía",
  "rooms": 1,
  "status": "active",
  "co2e": null,
  "created_at": "2025-06-01T10:30:00Z"
}

Example prompts:

"Log a 3-night hotel stay in Spain starting June 1st"
"Create a hotel stay at Hotel Berlin, check-in March 10, check-out March 12, 3 rooms"
"Add a hotel stay in France for the team offsite, 5 nights"

Common errors:

Error	Cause
422: “Either check_out_date or nights must be provided”	Neither duration method was given
422: “check_out_date must be on or after check_in_date”	Check-out is before check-in

`update_hotel_stay`

Update an existing hotel stay record. Only the fields you provide are changed. CO₂e is recalculated after update. Duration can be updated in two ways:

Provide check_out_date directly.
Provide nights (with or without a new check_in_date) — the check-out date is recalculated automatically.

Parameters:

Parameter	Type	Required	Default	Description
`hotel_stay_id`	string	Yes	—	UUID of the record. Use `list_hotel_stays` to find it
`check_in_date`	string	No	—	New check-in date (`YYYY-MM-DD`)
`check_out_date`	string	No	—	New check-out date (`YYYY-MM-DD`)
`nights`	integer	No	—	Number of nights (alternative to `check_out_date`, min 1)
`country`	string	No	—	New ISO-2 country code (e.g. `"ES"`, `"FR"`, `"US"`)
`name`	string	No	—	New guest or trip name
`hotel_name`	string	No	—	New hotel name
`address`	string	No	—	New hotel address
`rooms`	integer	No	—	New number of rooms (1-10,000)
`organization_id`	string	No	default org	Organization UUID

Example prompts:

"Change hotel stay abc-123 to 5 nights"
"Update the hotel stay country to France"
"Fix the hotel name on stay xyz to 'Hotel Gran Vía'"
"Change the check-in date to March 15th"

Common errors:

Error	Cause
404: “Hotel stay not found”	Invalid hotel stay UUID
422: “check_out_date must be on or after check_in_date”	Update would set check-out before check-in

Workflows

Querying hotel stays

List hotel stays — list_hotel_stays to query stays by date range or hotel name
View travel emissions — get_greenhouse_gas_emissions with category=travels for aggregated business travel totals
Compare with flights — list_business_travels to see flight/train records alongside hotel data

Logging a hotel stay

Create the stay — create_hotel_stay with check-in date, country, and nights or check-out date
Verify — list_hotel_stays after a few seconds to confirm creation and CO₂e calculation

API: Create Hotel Stay

REST API endpoint for hotel stay creation

API: List Hotel Stays

REST API equivalent with additional filters

Business Travels

Flight and train journey records

Emissions

Aggregated Scope 3 travel emissions

Getting Started

Tools Reference

Reference Data

Hotel Stay Tools

Hotel Stay Tools

`list_hotel_stays`

Write Operations

`create_hotel_stay`

`update_hotel_stay`

Workflows

Querying hotel stays

Logging a hotel stay

API: Create Hotel Stay

API: List Hotel Stays

Business Travels

Emissions

​Hotel Stay Tools

​list_hotel_stays

​Write Operations

​create_hotel_stay

​update_hotel_stay

​Workflows

​Querying hotel stays

​Logging a hotel stay

​Related

API: Create Hotel Stay

API: List Hotel Stays

Business Travels

Emissions

Hotel Stay Tools

`list_hotel_stays`

Write Operations

`create_hotel_stay`

`update_hotel_stay`

Workflows

Querying hotel stays

Logging a hotel stay

Related