> ## Documentation Index > Fetch the complete documentation index at: https://docs.gridbeds.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a reservation > Creates a reservation in the organization for an existing guest, named by `guest_id` (create one with `createGuest` first). Requires the `reservations.write` scope. The reservation is made `pending`. The API does not price the stay: the amounts you send are recorded as sent. It does check that the room type has a room free for every night, and answers 422 when it has not. Send an `Idempotency-Key` header to make a retry safe: for at least 24 hours, the same key with the same body answers with the first response instead of creating a second reservation. ## OpenAPI ````yaml /openapi/integration-v1.json post /v1/integration/reservations openapi: 3.1.2 info: title: Gridbeds Integration API version: 2.0.0 description: >- The Gridbeds public integration API. Authenticate with a scoped Bearer token issued to your installed app; every request is isolated to that app's organization. termsOfService: https://gridbeds.com/en/terms/ contact: name: Gridbeds support email: support@gridbeds.com license: name: Proprietary url: https://gridbeds.com/en/terms/ servers: - url: https://api.gridbeds.com/api description: Production - url: https://staging-api.gridbeds.com/api description: Sandbox security: - bearerAuth: [] tags: - name: Identity description: >- Who the token belongs to: the installation, its organization and the scopes it was granted. - name: Reservations description: The organization's reservations. - name: Guests description: The organization's guest profiles, which a reservation is made for. paths: /v1/integration/reservations: post: tags: - Reservations summary: Create a reservation description: >- Creates a reservation in the organization for an existing guest, named by `guest_id` (create one with `createGuest` first). Requires the `reservations.write` scope. The reservation is made `pending`. The API does not price the stay: the amounts you send are recorded as sent. It does check that the room type has a room free for every night, and answers 422 when it has not. Send an `Idempotency-Key` header to make a retry safe: for at least 24 hours, the same key with the same body answers with the first response instead of creating a second reservation. operationId: createReservation parameters: - name: Idempotency-Key in: header description: >- A key of your choosing, such as a UUID, that makes a retry safe: for at least 24 hours the same key with the same body answers with the first response instead of repeating the write. Only a successful response is remembered; after a failure the same key may be tried again. schema: type: string maxLength: 255 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StoreIntegrationReservationRequest' responses: '201': description: The reservation, as `getReservation` returns it. It is `pending`. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Reservation' meta: type: object properties: message: type: string const: Reservation created. required: - message required: - data - meta '401': description: >- Unauthenticated: the token is missing, unknown or revoked. A user's own sign-in token is refused the same way. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Forbidden. The token was not granted the `reservations.write` scope, or its installation is disabled or in error. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The first request with this `Idempotency-Key` is still being processed (`code`: `idempotency_in_flight`). Retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- The request failed validation (`errors` names each field), or it asks for something the organization cannot do (`code` says what). A repeated `Idempotency-Key` sent with a different body is refused too (`code`: `idempotency_key_reused`). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Too many requests: an installation may make 120 per minute. Wait `Retry-After` seconds. content: application/json: schema: $ref: '#/components/schemas/RateLimitError' headers: Retry-After: description: Seconds until the next request is counted afresh. schema: type: integer X-RateLimit-Limit: description: Requests allowed in the window. schema: type: integer X-RateLimit-Remaining: description: 'Requests left in the window: 0 here.' schema: type: integer X-RateLimit-Reset: description: When the window ends, as a Unix timestamp. schema: type: integer components: schemas: StoreIntegrationReservationRequest: type: object description: A reservation to create. It is made `pending`. properties: property_id: type: string format: uuid description: The property the stay is at. It must belong to the organization. room_type_id: type: string format: uuid description: >- The room type being booked. It must belong to `property_id`, and have a room free for every night of the stay. rate_plan_id: type: - string - 'null' format: uuid description: >- The rate plan the stay is sold under, recorded on the reservation. It must belong to `property_id`. The plan's restrictions, such as a minimum stay, are not checked. guest_id: type: string format: uuid description: >- The guest the reservation is for: an `id` from `listGuests`, or from `createGuest` for a guest not yet known. channel_id: type: - string - 'null' format: uuid description: >- The booking channel the reservation came through, when it came through one. check_in: type: string format: date description: The arrival date, as `YYYY-MM-DD`. Not before today. check_out: type: string format: date description: >- The departure date, as `YYYY-MM-DD`. After `check_in`, and at most 365 nights later. adults: type: integer description: How many adults are staying. minimum: 1 children: type: integer description: How many children are staying. Omit it for none. minimum: 0 infants: type: integer description: How many infants are staying. Omit it for none. minimum: 0 currency: type: string description: >- The three-letter ISO 4217 code of the amounts below. Omit it for the property's currency. base_price: type: number description: >- The price of the stay before fees, taxes and discounts. Not negative. Prices are recorded as sent: the API does not price the stay. minimum: 0 cleaning_fee: type: number description: The cleaning fee, recorded as sent. Not negative. Omit it for none. service_fee: type: number description: The service fee, recorded as sent. Not negative. Omit it for none. taxes: type: number description: >- The taxes on the stay, recorded as sent. Not negative. Omit it for none. discounts: type: number description: >- The discount given on the stay, recorded as sent. Not negative. Omit it for none. total_price: type: number description: >- The total price of the stay, in `currency`. Not negative. Recorded as sent. minimum: 0 special_requests: type: - string - 'null' description: What the guest asked for, in their words. internal_notes: type: - string - 'null' description: Notes for the property's staff. expected_arrival_time: type: - string - 'null' description: >- When the guest expects to arrive, as `HH:MM` on the property's clock. arrival_transport_mode: anyOf: - $ref: '#/components/schemas/ArrivalTransportMode' description: How the guest is travelling to the property. - type: 'null' arrival_transport_number: type: - string - 'null' description: >- The flight or train number, for `arrival_transport_mode`. Letters, digits, spaces and `-`, `/` or `.`. pattern: ^[\pL\pN][\pL\pN \-\/.]*$ maxLength: 20 required: - property_id - room_type_id - guest_id - check_in - check_out - adults - base_price - total_price title: StoreIntegrationReservationRequest Reservation: type: object properties: id: type: string format: uuid description: The reservation's id. organization_id: type: string format: uuid description: >- The organization the record belongs to: always the one that installed the app. status: $ref: '#/components/schemas/BookingStatus' description: >- Where the reservation stands in its life. | | |---| | `pending`
Received and waiting to be confirmed. | | `confirmed`
Confirmed by the property. | | `option`
Held for the guest until the hold expires or the property confirms it. The room is held meanwhile. | | `cancelled`
Cancelled. The room is free again. | | `no_show`
The guest did not arrive. The room is free again. | | `checked_in`
The guest has arrived and is staying. | | `checked_out`
The guest has left. | check_in: type: string format: date-time description: >- The arrival date. A calendar date, sent as a timestamp at midnight UTC (`2026-10-24T00:00:00.000000Z`): the time carries no meaning, read the date part. check_out: type: string format: date-time description: The departure date, sent the way `check_in` is. total_price: type: string description: >- The total price of the stay as a decimal string with two digits, in `currency`. currency: type: string description: >- The ISO 4217 code the prices are in. A reservation created without one is in its property's currency. guest_id: type: - string - 'null' format: uuid description: >- The guest the reservation is for: an `id` from `listGuests` or `createGuest`. required: - id - organization_id - status - check_in - check_out - total_price - currency - guest_id title: Reservation Error: type: object description: The body of a refused request. properties: message: type: string description: >- What went wrong, in a sentence for a person. Do not match on it: the wording can change and follows the request's language. code: type: string description: >- A stable identifier of the refusal, present when it has one, such as `idempotency_key_reused`. Match on this. errors: type: object description: >- Present on a validation failure: the messages for each field that failed, keyed by field name. additionalProperties: type: array items: type: string required: - message title: Error RateLimitError: type: object description: The body of a request refused for exceeding the installation's quota. properties: error: type: string description: Always `Too Many Requests`. message: type: string description: What happened, in a sentence for a person. retry_after: type: integer description: Seconds to wait before the next request. required: - error - message - retry_after title: RateLimitError ArrivalTransportMode: type: string description: > How the guest says they are reaching the property: by flight, train or car, or some other way. Deliberately coarse. It tells the property whether the number given with it is a flight or a train, and lets it plan a pickup; it is not a timetable. enum: - flight - train - car - other title: ArrivalTransportMode BookingStatus: type: string description: >- Booking status enumeration. Represents the possible states of a booking in the system. | | |---| | `pending`
Received and waiting to be confirmed. | | `confirmed`
Confirmed by the property. | | `option`
Held for the guest until the hold expires or the property confirms it. The room is held meanwhile. | | `cancelled`
Cancelled. The room is free again. | | `no_show`
The guest did not arrive. The room is free again. | | `checked_in`
The guest has arrived and is staying. | | `checked_out`
The guest has left. | enum: - pending - confirmed - option - cancelled - no_show - checked_in - checked_out title: BookingStatus securitySchemes: bearerAuth: type: http description: >- An integration token, sent as `Authorization: Bearer `. A token belongs to one installation of an app. Someone at the property who may manage its integrations installs the app in Gridbeds, under Settings → Integrations, and issues the token there, granting the scopes the app requested or a subset of them. The token is shown once; issuing a new one revokes the previous one. Every request reads and writes the data of the organization that installed the app, and nothing else. Each operation names the scope it requires. A token without that scope, and the token of an installation that is disabled or in error, are refused with 403; a token that is missing, unknown or revoked, and a user's own sign-in token, are refused with 401. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.