Termino Hotel API (1.2)
Download OpenAPI specification:
This document outlines the API of Termino, utilized by Slevomat.cz, s.ro. to enable the sale of online bookings on Slevomat.cz and Zlavomat.sk.
+This API is used for connecting channel management (CM) and property management systems (PMS).
+Core Functions of the API Include:
+-
+
- synchronization of hotel structure (room types and rooms) from CM/PMS to Termino or the other way around +
- synchronization of available capacities (free rooms) from CM/PMS to Termino +
- synchronization of rates, prices and booking restrictions (stop sale, closed departure/arrival, MLOS) +
- issuing reservations from Termino to CM/PMS +
- bi-directional editing and canceling of reservations created from Termino +
API Structure
+This API is bi-directional, meaning both sides can request or push information to the other's API. Given that this API covers various system setups, there are multiple ways to establish communication. The synchronization of hotel structure and capacities is typically achieved by CM/PMS pushing information to Termino. A periodic pull of capacity information can also be configured, but push is preferred as it facilitates faster change propagation and reduces traffic between systems.
+Typical usage for channel managers includes:
+-
+
- Implementing the
reservationandpingendpoints on your side
+ - Calling the
capacities-updateendpoint to push capacity changes
+ - Using the
get-hotelendpoint to retrieve the hotel structure and set up the connection
+
For property management systems, the typical usage involves:
+-
+
- Implementing the
hotel,reservation, andget-reservationendpoints. Thepingendpoint is not needed because thehotelendpoint should provide the same information (whether the hotel is active or not).
+ - Depending on the pull or push style, implementing the
capacitieson your side or calling thecapacities-updatepush endpoint on Termino to deliver updates.
+
All requests are required to communicate over HTTPS. Termino API endpoints support TLS protocol versions 1.2 and higher.
+Authentication
+All requests contain the property accessToken with a value assigned during the API verification process. These values identify the communicating parties - CM/PMS on one side and Termino on the other.
Both sides accept only HTTP POST. Requests and responses are sent with the Content-Type header set to application/json and a JSON body depending on the operation to be performed. Content encoding is always UTF-8.
If a message is received and processed, the HTTP response code should be 200 OK for successful results and any 4xx for unsuccessful results (the concrete error type is described in the response body).
5xx response codes indicate unexpected and internal errors, and the request can be retried without change. No specific response should be expected for server errors (JSON is not guaranteed). The response header Retry-After (if present) should be respected for retrying the request.
The type of message is determined by the URL.
+For push endpoints, the request should be repeated until it is successfully delivered to Termino. Similarly, Termino will repeat requests until they are accepted by your system. Successful delivery means either responding with success or an expected error described in the API specification.
+Identifiers
+-
+
- All identifiers (parameters named id) have to be unique for a given hotel, unless explicitly stated otherwise. +
- All identifiers generated on the Termino side are UUIDs. +
- All identifiers from your side can be either integers or strings. +
Date interval
+Date intervals are represented as objects with start and end properties, both formatted as YYYY-MM-DD. The start date is inclusive, while the end date is exclusive.
See DateInterval schema for details.
+{
+ "start": "2020-01-01",
+ "end": "2020-01-31"
+}
+Basic request
+{
+ "accessToken": "foobar",
+ // other properties
+}
+Basic success response
+{
+ "success": true,
+}
+Basic error response
+{
+ "error": {
+ "code": "invalid-access-token",
+ "message": "Access token not found."
+ }
+}
+Common error codes
+These errors can occur on any API endpoint.
+| Code | +Description | +
|---|---|
invalid-format |
+Unparsable JSON | +
missing-value |
+A required property is missing. | +
invalid-value |
+A property has invalid format (e.g., wrong date, time, datetime, interval, URL...). | +
invalid-access-token |
+Invalid or expired access token | +
Reservation ID
+Each reservation has to have a unique ID for reference between systems. This identifier is later used in case of modification and cancellation of the reservation is needed.
+Termino will preferably assign our identifier with reservation creation, or it can accept and later use the reservation ID returned in response. Using Termino's ID simplifies recovery from communication failures (phantom reservations).
+Money representation
+Money amounts are represented as strings in hundredths of currency unit. Currency is represented using ISO 4217 currency codes (e.g., "CZK" for Czech crowns, "EUR" for euros). Supported currencies are CZK, PLN, EUR and HUF.
+For example, an amount of one hundred Euros and fifty cents is represented as:
+{
+ "amount": "10050",
+ "currency": "EUR"
+}
+Rate plans
+Rate plan represents a sellable combination of room type, board type and other commercial conditions (cancellation policy, restrictions, etc.). Each rate plan has:
+-
+
id– partner-defined identifier (e.g. "HB", "NRF") -name– human readable name -pricingModel– defines how prices are provided in planning updates (per_room,per_person,per_occupancy) +Rate plans are provided in:
+- response of
/hotel(HotelInfo.ratePlans) - push updates via/hotel-update(ratePlans) - planning data via/planningand/planning-update(RatePlanPlanning)
+
Pricing models
+Three pricing models are supported for receiving planning updates:
+-
+
per_room- price is set per room and night
+per_person- price is set for count of persons and night
+per_occupancy- price set per night and occupancy (occupancy is specified count of adults and children)
+
Changes to API and its documentation
+2025
+?. ?. 2025
+-
+
- Added support for synchronization of rates, prices and booking restrictions via /planning-update and /planning endpoints +
2023
+2. 11. 2023
+-
+
- Added children ages and bed entitlement to reservation data (
reservation.children)
+ - Added meal plan to reservation data (
reservation.meal)
+ - Added e-mail address to reservation data (
reservation.contact.email)
+ - Deprecate
occupationsandoccupations-updateendpoints to be used for blockages. Use capacities instead.
+ - Deprecate
roomsparameter from RoomType structure. OnlyroomCountparameter is now needed to define room type structure
+ - Deprecate
roomIdparameter from Occupation and Reservation structure. OnlyroomTypeIdparameter is now needed to define occupation
+
2021
+24. 11. 2021
+-
+
- Deprecate checkIn, checkOut and url parameters from hotel structure +
2020
+9. 1. 2020
+-
+
- Initial release +
Endpoints on Termino side are called from PMS/CM system and mostly used to push data changes.
+If unsuccessful response is returned, the request has to be repeated until it is successfully delivered to Termino.
+Occupations (push)
Synchronization of changed reservations on the hotel side. +Usage:
+-
+
- Partner changes Slevomat reservation in their system and this endpoint is called to update the reservation in Termino/Slevomat +
- Data with reservations that were not originated from Termino/Slevomat are ignored +
Updates of occupations in multiple hotels has to be sent in multiple requests.
+Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Hotel id. + |
required | Array of objects (Occupation) List of updated occupations. + |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotelId": "string",
- "occupations": [
- {
- "id": "string",
- "type": "reservation",
- "status": "string",
- "roomId": "string",
- "roomTypeId": "string",
- "created": "2019-08-24T14:15:22Z",
- "term": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}
}
]
}Response samples
- 200
- 400
{- "success": true
}Capacities & planning (push)
Planning update of available capacities, booking restrictions (stop sale, closed arrival, closed departure, minimal length of stay), rateplans and prices.
+Granular updates are supported - you can include only availability, only rates, or both in the update. Similarly, rates update may include either prices or restrictions or both. Unchanged data should be omitted in the request.
+Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Your hotel id. + |
Array of objects (PlanningUpdate) |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotelId": "string",
- "update": [
- {
- "roomTypeId": 123,
- "availability": [
- {
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "availableRooms": 5
}
], - "rates": [
- {
- "ratePlanId": "HB",
- "planning": [
- {
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "perRoomPrice": {
- "amount": "string",
- "currency": "string"
}, - "perPersonPriceMatrix": [
- {
- "personsCount": 2,
- "price": {
- "amount": null,
- "currency": null
}, - "stopSale": false
}
], - "perOccupancyPriceMatrix": [
- {
- "adultsCount": 2,
- "childrenCount": 1,
- "price": {
- "amount": null,
- "currency": null
}, - "stopSale": false
}
], - "restrictions": {
- "closedForArrival": false,
- "closedForDeparture": false,
- "stopSale": false,
- "minimalLengthOfStay": 1,
- "maximalLengthOfStay": 0
}
}
]
}
], - "roomTypeRestrictions": [
- {
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "restrictions": {
- "closedForArrival": false,
- "closedForDeparture": false,
- "stopSale": false,
- "minimalLengthOfStay": 1,
- "maximalLengthOfStay": 0
}
}
]
}
]
}Response samples
- 200
- 400
{- "success": true
}Capacities (push) Deprecated
This endpoint is deprecated in favor of more powerful /planning-update. No removal is currently planned. Any new implementations should use /planning-update.
+Synchronization of changed capacities
+Usage:
+-
+
- CM / PMS pushes capacity changes to Termino +
Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Your hotel id. + |
required | Array of objects (Capacity) List of updated capacities. + |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotelId": "string",
- "capacities": [
- {
- "roomTypeId": 123,
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "availableRooms": 5
}
]
}Response samples
- 200
- 400
{- "success": true
}Hotel update (push)
Synchronization of changed hotel info and structure.
+Usage:
+-
+
- CM / PMS pushes hotel info and structure changes to Termino +
Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | Array of objects (Hotel) Updated hotel info. + |
Array of objects (RoomType) Updated room types. + | |
Array of objects (RatePlan) Updated rate plans. + |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotel": [
- {
- "id": "123456",
- "name": "Hotel Example",
- "address": {
- "street": "Pernerova 691",
- "city": "Praha 8",
- "country": "CZ"
}
}
], - "roomTypes": [
- {
- "id": "123456",
- "name": "Double room",
- "beds": 2,
- "extraBeds": 1,
- "roomsCount": 10,
- "rooms": [
- {
- "id": "125",
- "name": "Room 125"
}
]
}
], - "ratePlans": [
- {
- "id": "HB",
- "name": "Half-board",
- "pricingModel": "per_room"
}
]
}Response samples
- 200
- 400
{- "success": true
}Hotel info (reversed)
Provides same information as /hotel endpoint, but in reversed direction. This endpoint is called by CM to load room types and rate plans created on Termino side and set up mapping.
+Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Hotel id. + |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotelId": "string"
}Response samples
- 200
- 400
{- "hotel": {
- "id": "123456",
- "name": "Hotel Example",
- "address": {
- "street": "Pernerova 691",
- "city": "Praha 8",
- "country": "CZ"
}
}, - "roomTypes": [
- {
- "id": "123456",
- "name": "Double room",
- "beds": 2,
- "extraBeds": 1,
- "roomsCount": 10,
- "rooms": [
- {
- "id": "125",
- "name": "Room 125"
}
]
}
], - "ratePlans": [
- {
- "id": "HB",
- "name": "Half-board",
- "pricingModel": "per_room"
}
]
}Partner endpoints should be implemented in your PMS/CM system and are called by Termino, either periodically or when specific action is performed (eg. new reservation, hotel connection).
+Hotel, rooms and rates
Information about hotel for connection process and structure of room types and rate plans.
+Usage:
+-
+
- loading hotel info and structure when connecting new hotel to Termino +
- synchronizing hotel structure +
Request Body schema: application/json
| accessToken required | string Access token for authorization + |
required | string or integer Your hotel id + |
Responses
Request samples
- Payload
{- "accessToken": "aa5ae844-051c-4d30-9c67-54b70c99b580",
- "hotelId": "123456"
}Response samples
- 200
- 400
{- "hotel": {
- "id": "123456",
- "name": "Hotel Example",
- "address": {
- "street": "Pernerova 691",
- "city": "Praha 8",
- "country": "CZ"
}
}, - "roomTypes": [
- {
- "id": "123456",
- "name": "Double room",
- "beds": 2,
- "extraBeds": 1,
- "roomsCount": 10,
- "rooms": [
- {
- "id": "125",
- "name": "Room 125"
}
]
}
], - "ratePlans": [
- {
- "id": "HB",
- "name": "Half-board",
- "pricingModel": "per_room"
}
]
}Capacities Deprecated
This endpoint is deprecated is favor of more powerful /planning. No removal is currently planned. Any new implementations should use /planning.
+Synchronizing available rooms +Usage:
+-
+
- called when new hotel is registered +
- periodical synchronization of available space unless push endpoint is used +
Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Hotel id. + |
required | object (DateInterval) DateInterval is [start, end) – end date is exclusive. + |
Array of strings or integers Requested room type ids. When not provided, return capacities for all room types of given hotel. + |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotelId": "string",
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "roomTypeIds": [
- "string"
]
}Response samples
- 200
- 400
{- "capacities": [
- {
- "roomTypeId": 123,
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "availableRooms": 5
}
]
}Planning
Synchronizing available rooms, prices and booking restrictions (stop sale, closed arrival/departure, minimal length of stay) Usage:
+-
+
- called when new hotel is registered +
- periodical synchronization of available space, prices and restrictions unless push endpoint is used +
Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Hotel id. + |
required | object (DateInterval) DateInterval is [start, end) – end date is exclusive. + |
Array of strings or integers Requested room type ids. When not provided, return planning for all room types of given hotel. + |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotelId": "string",
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "roomTypeIds": [
- "string"
]
}Response samples
- 200
- 400
{- "planning": [
- {
- "roomTypeId": 123,
- "availability": [
- {
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "availableRooms": 5
}
], - "rates": [
- {
- "ratePlanId": "HB",
- "planning": [
- {
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "perRoomPrice": {
- "amount": "string",
- "currency": "string"
}, - "perPersonPriceMatrix": [
- {
- "personsCount": 2,
- "price": {
- "amount": null,
- "currency": null
}, - "stopSale": false
}
], - "perOccupancyPriceMatrix": [
- {
- "adultsCount": 2,
- "childrenCount": 1,
- "price": {
- "amount": null,
- "currency": null
}, - "stopSale": false
}
], - "restrictions": {
- "closedForArrival": false,
- "closedForDeparture": false,
- "stopSale": false,
- "minimalLengthOfStay": 1,
- "maximalLengthOfStay": 0
}
}
]
}
], - "roomTypeRestrictions": [
- {
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "restrictions": {
- "closedForArrival": false,
- "closedForDeparture": false,
- "stopSale": false,
- "minimalLengthOfStay": 1,
- "maximalLengthOfStay": 0
}
}
]
}
]
}Create/update reservation
Used to create, update, and cancel reservations.
+The exact behavior depends on the agreed communication scheme between Termino and your system.
+1 - Reservation Status Workflow
+A Dual-request mode (default)
+-
+
- First request —
status: option-
+
- Sent without customer data. +
- Blocks the room for the requested stay. +
+ - Second request —
status: confirmed-
+
- Includes customer data and final confirmation details. +
- Finalizes the reservation. +
+
This approach allows gradual state transitions and is the recommended mode for most partners.
+++⚠️ Important: Both
+optionandconfirmedstatuses are expected to block the room in your system.
B Single-request mode
+-
+
- The first
optionrequest already contains full customer data and voucher code.
+ - A subsequent
confirmedrequest may still be sent but does not need to be processed or relayed to the hotel.
+ - This mode is best suited for OTAs and other systems that cannot modify reservations after creation (except through cancel & rebook). +
You should confirm the preferred mode during your integration setup.
+2 - Reservation ID
+-
+
- You can use your ID (returned in the first response) or Termino's ID (preferred) +
- Using Termino's ID simplifies recovery from communication failures +
- Rooms must be blocked once an
optionrequest is processed successfully
+
Usage:
+-
+
- Called with status
optionand thenconfirmedwhen creating a new reservation (see above)
+ - Called with
canceledstatus to cancel the reservation
+ - Called when changing booking date on customer's request +
Grouped reservations are currently not implemented; one request always contains only one reservation. Reservation group ID is the same as reservation ID. Reservation response should contain the same data as the request.
+Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Your hotel id. + |
required | object (ReservationGroup) |
Responses
Request samples
- Payload
{- "accessToken": "11-11-11-11",
- "hotelId": 123456,
- "reservationGroup": {
- "id": 123456,
- "description": "New Year's Eve 2019",
- "totalPrice": {
- "amount": 1000,
- "currency": "CZK"
}, - "reservations": [
- {
- "id": 123456,
- "status": "option",
- "roomTypeId": 123,
- "term": {
- "start": "2019-01-01",
- "end": "2019-01-02"
}, - "price": {
- "amount": 1000,
- "currency": "CZK"
}, - "adultsCount": 2,
- "children": [
- {
- "age": 5,
- "bedEntitlement": true
}
], - "guestNote": "I would like to have a room with a view.",
- "voucher": "1234567890",
- "contact": {
- "name": "John Doe",
- "phone": "+420123456789"
}
}
]
}
}Response samples
- 200
- 400
{- "hotelId": "string",
- "accessToken": "string",
- "reservationGroup": {
- "id": "string",
- "description": "string",
- "reservations": [
- {
- "id": "string",
- "status": "option",
- "roomTypeId": "string",
- "ratePlanId": "string",
- "roomId": "string",
- "term": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "price": {
- "amount": "string",
- "currency": "string"
}, - "meal": "none",
- "adultsCount": 0,
- "childrenCount": 0,
- "children": [
- {
- "age": 0,
- "bedEntitlement": true
}
], - "guestNote": "string",
- "voucher": "string",
- "contact": {
- "name": "string",
- "phone": "string",
- "email": "string"
}
}
], - "totalPrice": {
- "amount": "string",
- "currency": "string"
}
}
}Reservation query
Request for current state of the reservation
+Usage:
+-
+
- queried by Termino when a reservation disappears from synchronized interval (moved to another room, term, room deleted etc.) without being updated first (failsafe). +
Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Hotel id. + |
required | string or integer Reservation id. + |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotelId": "string",
- "reservationId": "string"
}Response samples
- 200
- 400
{- "id": "string",
- "status": "option",
- "roomTypeId": "string",
- "ratePlanId": "string",
- "roomId": "string",
- "term": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "price": {
- "amount": "string",
- "currency": "string"
}, - "meal": "none",
- "adultsCount": 0,
- "childrenCount": 0,
- "children": [
- {
- "age": 0,
- "bedEntitlement": true
}
], - "guestNote": "string",
- "voucher": "string",
- "contact": {
- "name": "string",
- "phone": "string",
- "email": "string"
}
}Reservations search
Synchronization of changes in reservations created by Termino/Slevomat. This allows changes in reservation made in PMS to be propagated to Termino and Slevomat. Changes can also be pushed via /occupations-update endpoint. +Usage:
+-
+
- synchronizing occupation changes once a day +
Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Your hotel id. + |
required | object (DateInterval) DateInterval is [start, end) – end date is exclusive. + |
Array of strings or integers Filter occupations on given room types. + |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotelId": "string",
- "interval": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}, - "roomTypeIds": [
- "string"
]
}Response samples
- 200
- 400
{- "occupations": [
- {
- "id": "string",
- "type": "reservation",
- "status": "string",
- "roomId": "string",
- "roomTypeId": "string",
- "created": "2019-08-24T14:15:22Z",
- "term": {
- "start": "2019-08-24",
- "end": "2019-08-24"
}
}
]
}Ping
Ping endpoint is used to check if hotel exists and synchronization is active on your side.
+If you implement /hotel endpoint, you can ignore this endpoint.
+Usage:
+-
+
- called periodically to check if hotels are still active +
Request Body schema: application/jsonrequired
| accessToken required | string Access token to your API. + |
required | string or integer Hotel id. + |
Responses
Request samples
- Payload
{- "accessToken": "string",
- "hotelId": "string"
}Response samples
- 200
- 400
{- "success": true
}