{ "openapi": "3.1.0", "info": { "title": "BeachSTOCK API", "description": "Hotel availability, pricing, and booking for partners.\n\nEvery `/sto/v1/*` request must include the `x-api-key` header issued to your account.\n\nWorked examples, the booking flow and the retry rules are in the BeachSTOCK API Guide (PDF).", "version": "1.0" }, "paths": { "/sto/v1/hotels": { "get": { "tags": [ "Hotels" ], "summary": "Your hotels", "description": "Lists the hotels available to your account, including whether each hotel can be searched and booked. Only these hotelIds are accepted.", "operationId": "get_hotels_sto_v1_hotels_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HotelsResponse" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/availability": { "get": { "tags": [ "Availability" ], "summary": "Availability for a stay", "description": "Room availability for one of your hotels, per room unit per night, as Freesale, On Request or Stopsales. Give checkIn with either nights or checkOut (checkOut wins when both are sent); the range may not exceed 90 days.", "operationId": "get_availability_sto_v1_availability_get", "parameters": [ { "name": "hotelId", "in": "query", "required": true, "schema": { "type": "string", "title": "Hotelid" } }, { "name": "checkIn", "in": "query", "required": true, "schema": { "type": "string", "title": "Checkin" } }, { "name": "nights", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Nights" } }, { "name": "checkOut", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkout" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityResponse" } } } }, "400": { "description": "Malformed request, e.g. a forbidden field, unknown code, past checkIn, or a party/transfer mismatch.", "content": { "application/json": { "example": { "detail": "Field(s) not permitted: agentId" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/cache": { "get": { "tags": [ "Search" ], "summary": "Fast cache browse", "description": "A sub-second, pre-priced browse of the lead board across your hotels. mode: auto (cache, else a live search), cache (cache only) or hedge (both at once). Rows carry no resultId: to book, price the chosen hotel with POST /sto/v1/search/boards.", "operationId": "cache_browse_sto_v1_cache_get", "parameters": [ { "name": "checkIn", "in": "query", "required": true, "schema": { "type": "string", "title": "Checkin" } }, { "name": "nights", "in": "query", "required": true, "schema": { "type": "integer", "title": "Nights" } }, { "name": "adults", "in": "query", "required": false, "schema": { "type": "integer", "default": 2, "title": "Adults" } }, { "name": "children", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Children" } }, { "name": "infants", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "title": "Infants" } }, { "name": "hotelId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hotelid" } }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "default": "auto", "title": "Mode" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheResponse" } } } }, "400": { "description": "Malformed request, e.g. a forbidden field, unknown code, past checkIn, or a party/transfer mismatch.", "content": { "application/json": { "example": { "detail": "Field(s) not permitted: agentId" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/search": { "post": { "tags": [ "Search" ], "summary": "Search (lead board, fast)", "description": "One room per hotel at its lead-in board, priced with any applied offers. Omit hotelId to search every hotel on your account. Setting offer keeps only rooms the offer applies to. Book a result directly, or compare boards with POST /sto/v1/search/boards.", "operationId": "search_sto_v1_search_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Malformed request, e.g. a forbidden field, unknown code, past checkIn, or a party/transfer mismatch.", "content": { "application/json": { "example": { "detail": "Field(s) not permitted: agentId" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/search/boards": { "post": { "tags": [ "Search" ], "summary": "Board prices (every board, accurate)", "description": "Every room with every board basis, each accurately priced and bookable with its own resultId. The authoritative source of board prices. With a hotelId it is fast; without one it prices every hotel and board (about 20 seconds or more).", "operationId": "search_boards_sto_v1_search_boards_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardsResponse" } } } }, "400": { "description": "Malformed request, e.g. a forbidden field, unknown code, past checkIn, or a party/transfer mismatch.", "content": { "application/json": { "example": { "detail": "Field(s) not permitted: agentId" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/search/with-transfers": { "post": { "tags": [ "Search" ], "summary": "Search (lead board) + airport transfers in one call", "description": "The rooms of POST /sto/v1/search plus the airport transfer options for each hotel in the results, no slower than a plain search. Book a room resultId together with a transferResultId from the same response.", "operationId": "search_with_transfers_sto_v1_search_with_transfers_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchWithTransfersRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchWithTransfersResponse" } } } }, "400": { "description": "Malformed request, e.g. a forbidden field, unknown code, past checkIn, or a party/transfer mismatch.", "content": { "application/json": { "example": { "detail": "Field(s) not permitted: agentId" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/search/transfers": { "post": { "tags": [ "Search" ], "summary": "Airport transfers for a stay", "description": "Airport transfer options for a stay at one hotel: airport to hotel at the flight arrival and, with a departure, hotel to airport. A transfer is never booked on its own; pass its transferResultId to build with a room at the same hotel, for the same party and dates.", "operationId": "search_transfers_sto_v1_search_transfers_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferSearchRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransfersResponse" } } } }, "400": { "description": "Malformed request, e.g. a forbidden field, unknown code, past checkIn, or a party/transfer mismatch.", "content": { "application/json": { "example": { "detail": "Field(s) not permitted: agentId" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } }, "503": { "description": "Not available for your account or environment. Not retryable; contact support.", "content": { "application/json": { "example": { "detail": "Confirmation is disabled in this environment" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/reservations/{reservation_id}": { "get": { "tags": [ "Reservations" ], "summary": "Look up a reservation", "description": "The reservation summary, as returned by build and confirm. A reservation that does not belong to your account returns 404.", "operationId": "get_reservation_sto_v1_reservations__reservation_id__get", "parameters": [ { "name": "reservation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Reservation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reservation" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "404": { "description": "Reservation or result not found (or not yours).", "content": { "application/json": { "example": { "detail": "Reservation not found" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/reservations/{reservation_id}/erratas": { "get": { "tags": [ "Reservations" ], "summary": "Erratas for a reservation", "description": "The notices (erratas) the client must be advised of. Accept them at confirm.", "operationId": "get_reservation_erratas_sto_v1_reservations__reservation_id__erratas_get", "parameters": [ { "name": "reservation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Reservation Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErratasResponse" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "404": { "description": "Reservation or result not found (or not yours).", "content": { "application/json": { "example": { "detail": "Reservation not found" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/reservations": { "post": { "tags": [ "Reservations" ], "summary": "Build a reservation", "description": "Creates the unconfirmed reservation (status Quote) with its passengers, notes and any transfer, and returns its erratas. Nothing is booked until confirm. Re-sending the same request replays the same reservation; after a 502 or timeout, retry the same resultId.", "operationId": "create_reservation_sto_v1_reservations_post", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildResponse" } } } }, "400": { "description": "Malformed request, e.g. a forbidden field, unknown code, past checkIn, or a party/transfer mismatch.", "content": { "application/json": { "example": { "detail": "Field(s) not permitted: agentId" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "404": { "description": "Reservation or result not found (or not yours).", "content": { "application/json": { "example": { "detail": "Reservation not found" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "409": { "description": "Conflict: result in progress or expired, awaiting reconciliation, re-sent with a different booking, erratas not accepted, or the price changed (with currentPrice).", "content": { "application/json": { "example": { "detail": "The price has changed since you accepted it; resubmit expectedTotalPrice with the current amount to confirm.", "currentPrice": { "amount": 3010.11, "currency": "GBP" } }, "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } }, "503": { "description": "Not available for your account or environment. Not retryable; contact support.", "content": { "application/json": { "example": { "detail": "Confirmation is disabled in this environment" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } }, "/sto/v1/reservations/{reservation_id}/confirm": { "post": { "tags": [ "Reservations" ], "summary": "Confirm a reservation", "description": "Acknowledges the current price and accepts the erratas, then books. A price that no longer matches expectedTotalPrice returns 409 with currentPrice and books nothing. Idempotent: after a 5xx or timeout, retry the same confirm or look the reservation up; never re-book.", "operationId": "confirm_reservation_sto_v1_reservations__reservation_id__confirm_post", "parameters": [ { "name": "reservation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Reservation Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reservation" } } } }, "400": { "description": "Malformed request, e.g. a forbidden field, unknown code, past checkIn, or a party/transfer mismatch.", "content": { "application/json": { "example": { "detail": "Field(s) not permitted: agentId" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "401": { "description": "Unknown API key.", "content": { "application/json": { "example": { "detail": "Invalid API key" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "403": { "description": "The hotel or operation is not permitted for your account.", "content": { "application/json": { "example": { "detail": "Hotel is not permitted" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "404": { "description": "Reservation or result not found (or not yours).", "content": { "application/json": { "example": { "detail": "Reservation not found" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } }, "409": { "description": "Conflict: result in progress or expired, awaiting reconciliation, re-sent with a different booking, erratas not accepted, or the price changed (with currentPrice).", "content": { "application/json": { "example": { "detail": "The price has changed since you accepted it; resubmit expectedTotalPrice with the current amount to confirm.", "currentPrice": { "amount": 3010.11, "currency": "GBP" } }, "schema": { "$ref": "#/components/schemas/Conflict" } } } }, "422": { "description": "Missing or invalid fields, including a missing x-api-key header.", "content": { "application/json": { "example": { "detail": [ { "loc": [ "header", "x-api-key" ], "msg": "Field required", "type": "missing" } ] }, "schema": { "$ref": "#/components/schemas/ValidationErrorBody" } } } }, "500": { "description": "Unexpected error. For confirm, the booking may already be committed: retry or look it up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } } }, "502": { "description": "The booking system is temporarily unavailable. Safe to retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamError" } } } }, "503": { "description": "Not available for your account or environment. Not retryable; contact support.", "content": { "application/json": { "example": { "detail": "Confirmation is disabled in this environment" }, "schema": { "$ref": "#/components/schemas/ErrorDetail" } } } } }, "security": [ { "ApiKeyHeader": [] } ] } } }, "components": { "schemas": { "Applied": { "properties": { "offer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Offer", "description": "Full name of the occasion offer applied, or null.", "examples": [ "Honeymoon" ] }, "board": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Board", "description": "Full name of the pinned board, or null when each hotel is priced at its lead-in board.", "examples": [ "Half Board" ] }, "repeatClient": { "type": "boolean", "title": "Repeatclient" }, "longStay": { "type": "boolean", "title": "Longstay", "description": "True when the stay is 14+ nights and so qualifies for Long Stay pricing. Informational." } }, "type": "object", "required": [ "offer", "board", "repeatClient", "longStay" ], "title": "Applied" }, "AvailabilityResponse": { "properties": { "hotelId": { "type": "string", "title": "Hotelid", "examples": [ "8113" ] }, "hotelName": { "type": "string", "title": "Hotelname", "examples": [ "Victoria Beachcomber Resort & Spa" ] }, "checkIn": { "type": "string", "title": "Checkin", "examples": [ "2026-11-02" ] }, "checkOut": { "type": "string", "title": "Checkout", "examples": [ "2026-11-09" ] }, "units": { "items": { "$ref": "#/components/schemas/Unit" }, "type": "array", "title": "Units" } }, "type": "object", "required": [ "hotelId", "hotelName", "checkIn", "checkOut", "units" ], "title": "AvailabilityResponse" }, "Board": { "properties": { "name": { "type": "string", "title": "Name", "description": "Board basis name. On an occasion search this is the themed variant, e.g. \"Honeymoon Half Board with free light lunches\"." }, "reference": { "type": "string", "title": "Reference", "description": "Board code (AI, SP, HB, BB). Authoritative: key on this, not on the name.", "examples": [ "HB" ] } }, "type": "object", "required": [ "name", "reference" ], "title": "Board" }, "BoardPrice": { "properties": { "board": { "type": "string", "title": "Board", "description": "Board basis name.", "examples": [ "Half Board" ] }, "reference": { "type": "string", "title": "Reference", "description": "Board code (AI, SP, HB, BB).", "examples": [ "HB" ] }, "availability": { "type": "string", "enum": [ "Freesale", "On Request" ], "title": "Availability" }, "price": { "$ref": "#/components/schemas/Money", "description": "Accurate total at this board. On a net-priced account this is your estimated net." }, "grossPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Selling price. Net-priced accounts only." }, "specialOffers": { "items": { "$ref": "#/components/schemas/SpecialOffer" }, "type": "array", "title": "Specialoffers" }, "resultId": { "type": "string", "title": "Resultid", "description": "Single-use handle to book this room at this board.", "examples": [ "rsr_4fJ2kqT9" ] } }, "type": "object", "required": [ "board", "reference", "availability", "price", "specialOffers", "resultId" ], "title": "BoardPrice" }, "BoardsResponse": { "properties": { "hotelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hotelid", "description": "Echoes the request; null for an all-hotels search.", "examples": [ "8113" ] }, "checkIn": { "type": "string", "title": "Checkin", "examples": [ "2026-11-02" ] }, "checkOut": { "type": "string", "title": "Checkout", "examples": [ "2026-11-09" ] }, "results": { "items": { "$ref": "#/components/schemas/RoomBoards" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "hotelId", "checkIn", "checkOut", "results" ], "title": "BoardsResponse" }, "BookRequest": { "properties": { "resultId": { "type": "string", "title": "Resultid", "description": "The result to book, from /search or /search/boards. The board is encoded in it.", "examples": [ "rsr_4fJ2kqT9" ] }, "passengers": { "items": { "$ref": "#/components/schemas/PassengerInput" }, "type": "array", "title": "Passengers", "description": "One per guest. Must match the searched party's size and number of adults." }, "externalReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Externalreference", "description": "Your own reference, stored against the booking.", "examples": [ "PO-10442" ] }, "transferResultId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transferresultid", "description": "An airport transfer to add: same hotel and party, arriving on the check-in date.", "examples": [ "rsr_tXyZ81Lm" ] }, "flightDetails": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flightdetails", "description": "Free text.", "examples": [ "BA2287 arrives 14:30" ] }, "hotelRequests": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hotelrequests", "description": "Free text: room or hotel requests.", "examples": [ "Twin beds, near the beach" ] }, "clientRequests": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Clientrequests", "description": "Free text: client requests.", "examples": [ "Anniversary 5 Nov; nut allergy" ] } }, "type": "object", "required": [ "resultId", "passengers" ], "title": "BookRequest" }, "BuildResponse": { "properties": { "reservationId": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "title": "Reservationid", "description": "Use it verbatim in the reservation paths.", "examples": [ 511319 ] }, "status": { "type": "string", "title": "Status", "description": "Quote until confirmed, then Confirmed.", "examples": [ "Quote" ] }, "confirmationCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confirmationcode", "description": "Null until confirmed.", "examples": [ "B056985" ] }, "bookingReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bookingreference", "description": "Null until confirmed; equals confirmationCode.", "examples": [ "B056985" ] }, "leadPassenger": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Leadpassenger", "examples": [ "Ada Lovelace" ] }, "checkIn": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkin", "examples": [ "2026-11-02" ] }, "checkOut": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkout", "examples": [ "2026-11-09" ] }, "nights": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Nights", "examples": [ 7 ] }, "adultCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Adultcount", "examples": [ 2 ] }, "childCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Childcount", "examples": [ 0 ] }, "infantCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Infantcount", "examples": [ 0 ] }, "totalPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Totalprice", "description": "Reservation total, transfers included. On a net-priced account this is the exact net you pay.", "examples": [ 2970.11 ] }, "grossTotalPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Grosstotalprice", "description": "Selling price. Net-priced accounts only.", "examples": [ 3412.5 ] }, "commission": { "anyOf": [ { "$ref": "#/components/schemas/Commission" }, { "type": "null" } ], "description": "Net-priced accounts only." }, "currencyCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currencycode", "examples": [ "GBP" ] }, "transfers": { "items": { "$ref": "#/components/schemas/ReservationTransfer" }, "type": "array", "title": "Transfers", "description": "Airport transfer legs; empty when none." }, "erratas": { "items": { "$ref": "#/components/schemas/Errata" }, "type": "array", "title": "Erratas", "description": "Accept these at confirm." }, "notes": { "anyOf": [ { "$ref": "#/components/schemas/Notes" }, { "type": "null" } ], "description": "Outcome of the special-request notes." }, "quotedPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "The price you were shown at search (room plus any transfer). Compare with totalPrice." }, "partyChanged": { "anyOf": [ { "$ref": "#/components/schemas/PartyChanged" }, { "type": "null" } ], "description": "Present only when the booked party differs from the searched ages in a price-relevant way. Informational." } }, "type": "object", "required": [ "reservationId", "status", "confirmationCode", "bookingReference", "leadPassenger", "checkIn", "checkOut", "nights", "adultCount", "childCount", "infantCount", "totalPrice", "currencyCode", "transfers", "erratas" ], "title": "BuildResponse" }, "CacheResponse": { "properties": { "source": { "type": "string", "enum": [ "cache", "live" ], "title": "Source", "description": "cache: a cache hit. live: the auto/hedge fallback ran a live search." }, "checkIn": { "type": "string", "title": "Checkin", "examples": [ "2026-11-02" ] }, "nights": { "type": "integer", "title": "Nights", "examples": [ 7 ] }, "results": { "items": { "$ref": "#/components/schemas/CacheResult" }, "type": "array", "title": "Results", "description": "Browse only: rows carry no resultId. Price and book through /sto/v1/search/boards." } }, "type": "object", "required": [ "source", "checkIn", "nights", "results" ], "title": "CacheResponse" }, "CacheResult": { "properties": { "hotelId": { "type": "string", "title": "Hotelid", "examples": [ "8113" ] }, "hotelName": { "type": "string", "title": "Hotelname", "examples": [ "Victoria Beachcomber Resort & Spa" ] }, "room": { "type": "string", "title": "Room", "examples": [ "Ocean View Room" ] }, "board": { "$ref": "#/components/schemas/Board" }, "availability": { "type": "string", "enum": [ "Freesale", "On Request" ], "title": "Availability" }, "price": { "$ref": "#/components/schemas/Money", "description": "On a net-priced account this is your estimated net." }, "grossPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Selling price. Net-priced accounts only." }, "wasPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Pre-offer price for a was/now display. Only on cache rows, and null or absent unless higher than price." }, "grossWasPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Gross pre-offer price. Net-priced accounts only." }, "pricePerPerson": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Informational. Only on cache rows." }, "grossPricePerPerson": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Gross per person. Net-priced accounts only." }, "checkIn": { "type": "string", "title": "Checkin", "examples": [ "2026-11-02" ] }, "checkOut": { "type": "string", "title": "Checkout", "examples": [ "2026-11-09" ] }, "nights": { "type": "integer", "title": "Nights", "examples": [ 7 ] }, "specialOffers": { "items": { "$ref": "#/components/schemas/SpecialOffer" }, "type": "array", "title": "Specialoffers" } }, "type": "object", "required": [ "hotelId", "hotelName", "room", "board", "availability", "price", "checkIn", "checkOut", "nights", "specialOffers" ], "title": "CacheResult" }, "Commission": { "properties": { "amount": { "type": "number", "title": "Amount", "description": "Commission deducted.", "examples": [ 341.25 ] }, "vat": { "type": "number", "title": "Vat", "description": "VAT on the commission. Deducted only when vatSelfBilling is true.", "examples": [ 68.25 ] }, "vatSelfBilling": { "type": "boolean", "title": "Vatselfbilling" }, "currency": { "type": "string", "title": "Currency", "examples": [ "GBP" ] } }, "type": "object", "required": [ "amount", "vat", "vatSelfBilling", "currency" ], "title": "Commission" }, "ConfirmRequest": { "properties": { "acceptErrataIds": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "title": "Accepterrataids", "description": "The errataIds you accept." }, "acceptAllErratas": { "type": "boolean", "title": "Acceptallerratas", "description": "true to accept every errata.", "default": false }, "expectedTotalPrice": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ], "title": "Expectedtotalprice", "description": "The totalPrice from the build response that you accept. Needed to confirm (400 without it); not needed to replay a confirmed booking.", "examples": [ 2970.11 ] }, "expectedCurrency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expectedcurrency", "description": "Its currency. Needed with expectedTotalPrice.", "examples": [ "GBP" ] } }, "type": "object", "title": "ConfirmRequest" }, "Conflict": { "properties": { "detail": { "type": "string", "title": "Detail", "description": "What was wrong with the request.", "examples": [ "Hotel is not permitted" ] }, "currentPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Only when the price changed at confirm: the current total. Resubmit with this amount." } }, "type": "object", "required": [ "detail" ], "title": "Conflict" }, "Errata": { "properties": { "errataId": { "type": "integer", "title": "Errataid", "examples": [ 1178583 ] }, "type": { "type": "string", "title": "Type", "examples": [ "Generic" ] }, "text": { "type": "string", "title": "Text", "description": "Notice the client must be advised of before confirming.", "examples": [ "A Tourist Fee of EUR 3 per person per night applies in Mauritius..." ] }, "accepted": { "type": "boolean", "title": "Accepted" } }, "type": "object", "required": [ "errataId", "type", "text", "accepted" ], "title": "Errata" }, "ErratasResponse": { "properties": { "reservationId": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "title": "Reservationid", "examples": [ 511319 ] }, "erratas": { "items": { "$ref": "#/components/schemas/Errata" }, "type": "array", "title": "Erratas" } }, "type": "object", "required": [ "reservationId", "erratas" ], "title": "ErratasResponse" }, "ErrorDetail": { "properties": { "detail": { "type": "string", "title": "Detail", "description": "What was wrong with the request.", "examples": [ "Hotel is not permitted" ] } }, "type": "object", "required": [ "detail" ], "title": "ErrorDetail" }, "Hotel": { "properties": { "hotelId": { "type": "string", "title": "Hotelid", "description": "Identifier to pass to availability and search.", "examples": [ "8113" ] }, "hotelName": { "type": "string", "title": "Hotelname", "examples": [ "Victoria Beachcomber Resort & Spa" ] }, "canSearch": { "type": "boolean", "title": "Cansearch", "description": "Your account may search this hotel." }, "canBook": { "type": "boolean", "title": "Canbook", "description": "Your account may book this hotel." } }, "type": "object", "required": [ "hotelId", "hotelName", "canSearch", "canBook" ], "title": "Hotel" }, "HotelTransfers": { "properties": { "hotelId": { "type": "string", "title": "Hotelid", "examples": [ "8113" ] }, "hotelName": { "type": "string", "title": "Hotelname", "examples": [ "Victoria Beachcomber Resort & Spa" ] }, "options": { "items": { "$ref": "#/components/schemas/TransferOption" }, "type": "array", "title": "Options" }, "unavailable": { "anyOf": [ { "type": "string", "enum": [ "not_configured", "upstream_error" ] }, { "type": "null" } ], "title": "Unavailable", "description": "Present, with empty options, when transfers could not be priced for this hotel. The rooms are still returned." } }, "type": "object", "required": [ "hotelId", "hotelName", "options" ], "title": "HotelTransfers" }, "HotelsResponse": { "properties": { "hotels": { "items": { "$ref": "#/components/schemas/Hotel" }, "type": "array", "title": "Hotels" } }, "type": "object", "required": [ "hotels" ], "title": "HotelsResponse" }, "InternalError": { "properties": { "error": { "type": "string", "const": "internal_error", "title": "Error" }, "message": { "type": "string", "title": "Message", "examples": [ "The request could not be completed." ] } }, "type": "object", "required": [ "error", "message" ], "title": "InternalError" }, "Money": { "properties": { "amount": { "type": "number", "title": "Amount", "description": "Amount in major units, e.g. 2381.78.", "examples": [ 2381.78 ] }, "currency": { "type": "string", "title": "Currency", "description": "ISO 4217 currency code, e.g. GBP.", "examples": [ "GBP" ] } }, "type": "object", "required": [ "amount", "currency" ], "title": "Money" }, "NightStatus": { "properties": { "date": { "type": "string", "title": "Date", "description": "YYYY-MM-DD.", "examples": [ "2026-11-02" ] }, "status": { "type": "string", "enum": [ "Freesale", "On Request", "Stopsales" ], "title": "Status" } }, "type": "object", "required": [ "date", "status" ], "title": "NightStatus" }, "Notes": { "properties": { "attached": { "items": { "type": "string" }, "type": "array", "title": "Attached", "description": "Request fields recorded on the booking.", "examples": [ [ "hotelRequests" ] ] }, "failed": { "items": { "type": "string" }, "type": "array", "title": "Failed", "description": "Request fields NOT recorded; resubmit or pass to support.", "examples": [ [] ] }, "resentOnReplay": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Resentonreplay", "description": "On a build replay: whether notes were sent again (they are not)." } }, "type": "object", "title": "Notes" }, "PartyChanged": { "properties": { "searched": { "$ref": "#/components/schemas/PartyProfile" }, "booked": { "$ref": "#/components/schemas/PartyProfile" } }, "type": "object", "required": [ "searched", "booked" ], "title": "PartyChanged" }, "PartyProfile": { "properties": { "adults": { "type": "integer", "title": "Adults", "examples": [ 2 ] }, "childAges": { "items": { "type": "integer" }, "type": "array", "title": "Childages", "examples": [ [ 10 ] ] } }, "type": "object", "required": [ "adults", "childAges" ], "title": "PartyProfile" }, "PassengerInput": { "properties": { "type": { "type": "string", "enum": [ "Adult", "Child", "Infant" ], "title": "Type", "description": "A Child or Infant must be 0-17 on the check-in date.", "default": "Adult" }, "title": { "type": "string", "minLength": 1, "title": "Title", "default": "Mr", "examples": [ "Ms" ] }, "forename": { "type": "string", "minLength": 1, "title": "Forename", "examples": [ "Ada" ] }, "surname": { "type": "string", "minLength": 1, "title": "Surname", "examples": [ "Lovelace" ] }, "dateOfBirth": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dateofbirth", "description": "YYYY-MM-DD. Must be sent for every passenger (400 if missing); prices and age bands are set from it.", "examples": [ "1990-12-10" ] }, "isLead": { "type": "boolean", "title": "Islead", "description": "true for exactly one passenger.", "default": false } }, "type": "object", "required": [ "forename", "surname" ], "title": "PassengerInput" }, "Reservation": { "properties": { "reservationId": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "title": "Reservationid", "description": "Use it verbatim in the reservation paths.", "examples": [ 511319 ] }, "status": { "type": "string", "title": "Status", "description": "Quote until confirmed, then Confirmed.", "examples": [ "Quote" ] }, "confirmationCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Confirmationcode", "description": "Null until confirmed.", "examples": [ "B056985" ] }, "bookingReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Bookingreference", "description": "Null until confirmed; equals confirmationCode.", "examples": [ "B056985" ] }, "leadPassenger": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Leadpassenger", "examples": [ "Ada Lovelace" ] }, "checkIn": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkin", "examples": [ "2026-11-02" ] }, "checkOut": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkout", "examples": [ "2026-11-09" ] }, "nights": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Nights", "examples": [ 7 ] }, "adultCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Adultcount", "examples": [ 2 ] }, "childCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Childcount", "examples": [ 0 ] }, "infantCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Infantcount", "examples": [ 0 ] }, "totalPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Totalprice", "description": "Reservation total, transfers included. On a net-priced account this is the exact net you pay.", "examples": [ 2970.11 ] }, "grossTotalPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Grosstotalprice", "description": "Selling price. Net-priced accounts only.", "examples": [ 3412.5 ] }, "commission": { "anyOf": [ { "$ref": "#/components/schemas/Commission" }, { "type": "null" } ], "description": "Net-priced accounts only." }, "currencyCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currencycode", "examples": [ "GBP" ] }, "transfers": { "items": { "$ref": "#/components/schemas/ReservationTransfer" }, "type": "array", "title": "Transfers", "description": "Airport transfer legs; empty when none." } }, "type": "object", "required": [ "reservationId", "status", "confirmationCode", "bookingReference", "leadPassenger", "checkIn", "checkOut", "nights", "adultCount", "childCount", "infantCount", "totalPrice", "currencyCode", "transfers" ], "title": "Reservation" }, "ReservationTransfer": { "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Name", "description": "Route, e.g. \"Airport > Hotel\".", "examples": [ "Mauritius Airport > Victoria Beachcomber Resort & Spa" ] }, "pickupDateTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Pickupdatetime", "examples": [ "2026-11-02T14:30:00" ] }, "price": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] } }, "type": "object", "required": [ "name", "pickupDateTime", "price" ], "title": "ReservationTransfer" }, "RoomBoards": { "properties": { "hotelId": { "type": "string", "title": "Hotelid", "examples": [ "8113" ] }, "hotelName": { "type": "string", "title": "Hotelname", "examples": [ "Victoria Beachcomber Resort & Spa" ] }, "room": { "type": "string", "title": "Room", "examples": [ "Ocean View Room" ] }, "boards": { "items": { "$ref": "#/components/schemas/BoardPrice" }, "type": "array", "title": "Boards", "description": "Every board basis for the room, lead board first." } }, "type": "object", "required": [ "hotelId", "hotelName", "room", "boards" ], "title": "RoomBoards" }, "SearchRequest": { "properties": { "hotelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hotelid", "description": "One of your hotels; omit to search them all.", "examples": [ "8113" ] }, "checkIn": { "type": "string", "title": "Checkin", "description": "Arrival date, YYYY-MM-DD. Must not be in the past.", "examples": [ "2026-11-02" ] }, "nights": { "type": "integer", "title": "Nights", "description": "Length of stay, 1 or more.", "examples": [ 7 ] }, "passengerAges": { "items": { "type": "integer" }, "type": "array", "title": "Passengerages", "description": "One age per guest, children and infants included.", "default": [ 30, 30 ], "examples": [ [ 30, 30, 10 ] ] }, "offer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Offer", "description": "Occasion offer: HM (Honeymoon), WA (Wedding Anniversary), FM (Familymoon), WD (Wedding Party). Returns only rooms the offer applies to. Not accepted on /search/boards.", "examples": [ "HM" ] }, "board": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Board", "description": "Board to price at: AI, SP, HB or BB. Omit for each hotel's lead-in board. Not accepted on /search/boards.", "examples": [ "AI" ] }, "repeatClient": { "type": "boolean", "title": "Repeatclient", "description": "Apply the repeat-client offer where it applies; never narrows the results.", "default": false } }, "type": "object", "required": [ "checkIn", "nights" ], "title": "SearchRequest" }, "SearchResponse": { "properties": { "hotelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hotelid", "description": "Echoes the request; null for an all-hotels search.", "examples": [ "8113" ] }, "checkIn": { "type": "string", "title": "Checkin", "examples": [ "2026-11-02" ] }, "checkOut": { "type": "string", "title": "Checkout", "examples": [ "2026-11-09" ] }, "applied": { "$ref": "#/components/schemas/Applied" }, "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array", "title": "Results" } }, "type": "object", "required": [ "hotelId", "checkIn", "checkOut", "applied", "results" ], "title": "SearchResponse" }, "SearchResult": { "properties": { "resultId": { "type": "string", "title": "Resultid", "description": "Opaque, single-use handle to book this result. Valid about 10 minutes.", "examples": [ "rsr_4fJ2kqT9" ] }, "hotelId": { "type": "string", "title": "Hotelid", "examples": [ "8113" ] }, "hotelName": { "type": "string", "title": "Hotelname", "examples": [ "Victoria Beachcomber Resort & Spa" ] }, "room": { "type": "string", "title": "Room", "examples": [ "Ocean View Room" ] }, "availability": { "type": "string", "enum": [ "Freesale", "On Request" ], "title": "Availability", "description": "Both values are bookable." }, "board": { "$ref": "#/components/schemas/Board" }, "price": { "$ref": "#/components/schemas/Money", "description": "Total for the stay at this board, offers applied. On a net-priced account this is your estimated net." }, "grossPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Selling price. Net-priced accounts only." }, "specialOffers": { "items": { "$ref": "#/components/schemas/SpecialOffer" }, "type": "array", "title": "Specialoffers", "description": "Offers applied automatically. Informational; already in price." } }, "type": "object", "required": [ "resultId", "hotelId", "hotelName", "room", "availability", "board", "price", "specialOffers" ], "title": "SearchResult" }, "SearchWithTransfersRequest": { "properties": { "hotelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hotelid", "description": "One of your hotels; omit to search them all.", "examples": [ "8113" ] }, "checkIn": { "type": "string", "title": "Checkin", "description": "Arrival date, YYYY-MM-DD. Must not be in the past.", "examples": [ "2026-11-02" ] }, "nights": { "type": "integer", "title": "Nights", "description": "Length of stay, 1 or more.", "examples": [ 7 ] }, "passengerAges": { "items": { "type": "integer" }, "type": "array", "title": "Passengerages", "description": "One age per guest, children and infants included.", "default": [ 30, 30 ], "examples": [ [ 30, 30, 10 ] ] }, "offer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Offer", "description": "Occasion offer: HM (Honeymoon), WA (Wedding Anniversary), FM (Familymoon), WD (Wedding Party). Returns only rooms the offer applies to. Not accepted on /search/boards.", "examples": [ "HM" ] }, "board": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Board", "description": "Board to price at: AI, SP, HB or BB. Omit for each hotel's lead-in board. Not accepted on /search/boards.", "examples": [ "AI" ] }, "repeatClient": { "type": "boolean", "title": "Repeatclient", "description": "Apply the repeat-client offer where it applies; never narrows the results.", "default": false }, "arrivalTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Arrivaltime", "description": "Flight arrival, local HH:MM, on the check-in date. Defaults to a standard time (typically 14:30).", "examples": [ "14:30" ] }, "departureTime": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Departuretime", "description": "Flight departure, local HH:MM, on the check-out date. Defaults to a standard time (typically 18:00).", "examples": [ "18:00" ] }, "returnTransfer": { "type": "boolean", "title": "Returntransfer", "description": "false for airport to hotel only.", "default": true }, "allCombinations": { "type": "boolean", "title": "Allcombinations", "description": "As on POST /sto/v1/search/transfers.", "default": false } }, "type": "object", "required": [ "checkIn", "nights" ], "title": "SearchWithTransfersRequest" }, "SearchWithTransfersResponse": { "properties": { "hotelId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hotelid", "description": "Echoes the request; null for an all-hotels search.", "examples": [ "8113" ] }, "checkIn": { "type": "string", "title": "Checkin", "examples": [ "2026-11-02" ] }, "checkOut": { "type": "string", "title": "Checkout", "examples": [ "2026-11-09" ] }, "applied": { "$ref": "#/components/schemas/Applied" }, "results": { "items": { "$ref": "#/components/schemas/SearchResult" }, "type": "array", "title": "Results" }, "arrival": { "type": "string", "title": "Arrival", "description": "Resolved flight arrival, YYYY-MM-DDTHH:MM.", "examples": [ "2026-11-02T14:30" ] }, "departure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Departure", "description": "Resolved flight departure; null when returnTransfer is false.", "examples": [ "2026-11-09T18:00" ] }, "transfers": { "items": { "$ref": "#/components/schemas/HotelTransfers" }, "type": "array", "title": "Transfers", "description": "One entry per hotel in results." } }, "type": "object", "required": [ "hotelId", "checkIn", "checkOut", "applied", "results", "arrival", "departure", "transfers" ], "title": "SearchWithTransfersResponse" }, "SpecialOffer": { "properties": { "name": { "type": "string", "title": "Name", "description": "Offer name, e.g. \"Early Booking Offer\"." }, "price": { "$ref": "#/components/schemas/Money", "description": "The offer's effect on the price (negative for a discount)." }, "grossPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Selling-price effect. Net-priced accounts only." } }, "type": "object", "required": [ "name", "price" ], "title": "SpecialOffer" }, "TransferLeg": { "properties": { "from": { "type": "string", "title": "From", "examples": [ "Mauritius Airport" ] }, "to": { "type": "string", "title": "To", "examples": [ "Victoria Beachcomber Resort & Spa" ] }, "pickupDateTime": { "type": "string", "title": "Pickupdatetime", "description": "Local date-time, YYYY-MM-DDTHH:MM:SS.", "examples": [ "2026-11-02T14:30:00" ] }, "vehicle": { "type": "string", "title": "Vehicle", "examples": [ "MU Private Car" ] }, "price": { "$ref": "#/components/schemas/Money" }, "grossPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Selling price. Net-priced accounts only." } }, "type": "object", "required": [ "from", "to", "pickupDateTime", "vehicle", "price" ], "title": "TransferLeg" }, "TransferOption": { "properties": { "transferResultId": { "type": "string", "title": "Transferresultid", "description": "Opaque, single-use handle. Pass it to build with a room at the same hotel. Valid about 10 minutes.", "examples": [ "rsr_tXyZ81Lm" ] }, "vehicle": { "type": "string", "title": "Vehicle", "examples": [ "MU Private Car" ] }, "returnVehicle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Returnvehicle", "description": "Null for a one-way transfer.", "examples": [ "MU Private Car" ] }, "outbound": { "$ref": "#/components/schemas/TransferLeg" }, "return": { "anyOf": [ { "$ref": "#/components/schemas/TransferLeg" }, { "type": "null" } ], "description": "Null for a one-way transfer." }, "price": { "$ref": "#/components/schemas/Money", "description": "Total for both legs. On a net-priced account this is your estimated net." }, "grossPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "Selling price. Net-priced accounts only." } }, "type": "object", "required": [ "transferResultId", "vehicle", "returnVehicle", "outbound", "return", "price" ], "title": "TransferOption" }, "TransferSearchRequest": { "properties": { "hotelId": { "type": "string", "title": "Hotelid", "description": "The hotel of the stay.", "examples": [ "8113" ] }, "arrival": { "type": "string", "title": "Arrival", "description": "Flight arrival, local YYYY-MM-DDTHH:MM, on the check-in date.", "examples": [ "2026-11-02T14:30" ] }, "departure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Departure", "description": "Flight departure, local YYYY-MM-DDTHH:MM, on the check-out date. Include it for a return transfer.", "examples": [ "2026-11-09T18:00" ] }, "passengerAges": { "items": { "type": "integer" }, "type": "array", "title": "Passengerages", "description": "One age per guest, as for the room.", "default": [ 30, 30 ] }, "allCombinations": { "type": "boolean", "title": "Allcombinations", "description": "false: only options whose outbound and return vehicle match. true: every pairing.", "default": false } }, "type": "object", "required": [ "hotelId", "arrival" ], "title": "TransferSearchRequest" }, "TransfersResponse": { "properties": { "hotelId": { "type": "string", "title": "Hotelid", "examples": [ "8113" ] }, "hotelName": { "type": "string", "title": "Hotelname", "examples": [ "Victoria Beachcomber Resort & Spa" ] }, "arrival": { "type": "string", "title": "Arrival", "examples": [ "2026-11-02T14:30" ] }, "departure": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Departure", "examples": [ "2026-11-09T18:00" ] }, "results": { "items": { "$ref": "#/components/schemas/TransferOption" }, "type": "array", "title": "Results", "description": "Sorted by price." } }, "type": "object", "required": [ "hotelId", "hotelName", "arrival", "departure", "results" ], "title": "TransfersResponse" }, "Unit": { "properties": { "unitId": { "type": "integer", "title": "Unitid", "examples": [ 207280 ] }, "unitName": { "type": "string", "title": "Unitname", "examples": [ "Ocean View Room" ] }, "unitType": { "type": "string", "title": "Unittype", "examples": [ "Unit" ] }, "availability": { "items": { "$ref": "#/components/schemas/NightStatus" }, "type": "array", "title": "Availability", "description": "One entry per night in the range." } }, "type": "object", "required": [ "unitId", "unitName", "unitType", "availability" ], "title": "Unit" }, "UpstreamError": { "properties": { "error": { "type": "string", "const": "upstream_error", "title": "Error" }, "message": { "type": "string", "title": "Message", "description": "Names the step that failed where known, with a support reference matching the X-Request-Id header.", "examples": [ "The booking system could not complete the request while adding the room to this reservation. Please try again; if it persists, quote reference 3f2c9a1e." ] } }, "type": "object", "required": [ "error", "message" ], "title": "UpstreamError" }, "ValidationErrorBody": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationIssue" }, "type": "array", "title": "Detail", "examples": [ "Hotel is not permitted" ] } }, "type": "object", "required": [ "detail" ], "title": "ValidationErrorBody" }, "ValidationIssue": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Loc", "examples": [ [ "body", "passengers", 0, "forename" ] ] }, "msg": { "type": "string", "title": "Msg", "examples": [ "String should have at least 1 character" ] }, "type": { "type": "string", "title": "Type", "examples": [ "string_too_short" ] }, "ctx": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Ctx", "description": "Constraint details, e.g. {\"min_length\": 1}, when a value breaks a constraint." } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationIssue" } }, "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key" } } }, "tags": [ { "name": "Hotels", "description": "The hotels your account can search and book." }, { "name": "Availability", "description": "Whether a stay has rooms, before pricing it." }, { "name": "Search", "description": "The three ways to shop: a fast lead-board search, accurate per-board pricing, and the pre-priced cache browse." }, { "name": "Reservations", "description": "Build, confirm, and look up a reservation." } ], "servers": [ { "url": "https://api.beachcomberapi.uk" } ] }