---
title: "Add a stay"
method: POST
path: "/api/trips/{id}/stays"
tags: ["Stays"]
---

# Add a stay

`POST /api/trips/{id}/stays`

## Request

- Base URL: `https://trvlrr.app`
- URL: `https://trvlrr.app/api/trips/{id}/stays`
- Auth: HTTP bearer

Accommodation on a trip. country is stored as its readable name. A city given here is recorded among the trip's places. Travellers default to the trip's.

## Path parameters

- `id` string, required: The trip id.

## Request body

- StayCreate
  - `property` string, required: Hotel or place name.
  - `provider` string, nullable: Booked with, e.g. Booking.com or the hotel chain.
  - `city` string, nullable: City the stay is in.
  - `country` string, nullable: Country (name or ISO code).
  - `locality` string, nullable: The city it belongs to, when the label is a suburb or area.
  - `locality_country` string, nullable: ISO alpha-2 of that city.
  - `address` string, nullable: Street address.
  - `check_in` string, nullable: Check-in date. Date, YYYY-MM-DD.
  - `check_out` string, nullable: Check-out date. Date, YYYY-MM-DD.
  - `check_in_time` string, nullable: Check-in time, HH:MM local; empty means mid-afternoon.
  - `check_out_time` string, nullable: Check-out time, HH:MM local; empty means late morning.
  - `booking_ref` string, nullable: Confirmation number.
  - `price_raw` string, nullable: Price with currency, e.g. "EUR 540".
  - `room_type` string, nullable: Room type.
  - `guests` integer, nullable: Number of guests.
  - `lat` number, nullable: Latitude.
  - `lon` number, nullable: Longitude.
  - `tz` string, nullable: IANA time zone.
  - `check_in_utc` string, nullable: Derived; only set to override.
  - `check_out_utc` string, nullable: Derived; only set to override.
  - `status` string, nullable: Free text, e.g. "Confirmed".
  - `notes` string, nullable: Anything else worth keeping.
  - `agency` string, nullable: Booked through.
  - `payment_status` 'paid' | 'due' | 'on_arrival' | 'null', nullable: paid, due (to pay before the trip) or on_arrival (pay there or on the day).
  - `payment_method` 'card' | 'cash' | 'null', nullable: card or cash.
  - `traveler_ids` string[]: Who stayed; defaults to the trip's travellers.

## Response `201`

The new stay's id.

- Created
  - `id` string, required

## Other responses

- `400`: The request is malformed or fails validation.
- `401`: No usable credential: a Clerk session token, a device token or an OAuth access token is required.
- `403`: The caller may not do this to this account or trip.
- `404`: No such thing, or not one the caller can see.

---

[API](https://skmtc.dev/trvlrr/apis/trvlrr-api.md) · [All operations](https://skmtc.dev/trvlrr/apis/trvlrr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trvlrr/apis/trvlrr-api/revisions/ea024946b293?raw)