Implementation Guide - Ratefox V2
🔧 Introduction
RateFox is an advanced solution built to empower travel companies by optimizing booking profitability in real time.
RateFox integrates seamlessly into your existing booking flow with a single API call, made just before the Booking Request. This implementation guide will walk you through each step required to successfully integrate RateFox into your system.
Notes and Tips :
Recommended Guides prior to Implementation / Evaluation -
In this guide, you will find detailed information on:
- ✅ Authentication Method
- 🔄 Request and Response Structure
- 🧾 Field Descriptions
- 📘 Use Case Examples
- 🧪 Evaluation and Integration Steps
- 🧠 Best Practices for Optimal Performance
Code Examples
For each code example provided, you’ll also find versions in multiple programming languages. Simply click “More Code Examples” below each section to view them :
- Shell
- Python
- Node
- Ruby
- Objective-C
- PHP
- C
- C++
- C#
- Clojure
- Go
- HTTP
- Java
- Javascript
- JSON
- Kotlin
- PowerShell
- OCaml
- R
- Swift
🔑 Authentication
The RateFox API uses HTTP Basic Authentication to securely authorize requests. Each API call must include a Base64-encoded username and password in the request header.
Authentication Format
To construct the Authorization header - Combine your username and password with a colon (:).
Example :
If your Username is “
api_user
” and Password is “secret123
”.Combined string: “
api_user:secret123
”.Base64 encoded: "
YXBpX3VzZXI6c2VjcmV0MTIz
”Header :
Authorization : Basic YXBpX3VzZXI6c2VjcmV0MTIz
Code Example :
curl -X GET 'https://api.example.com/endpoint' \ -H 'Authorization: Basic YXBpX3VzZXI6c2VjcmV0MTIz'
🛠️ Endpoint Reference
Base URL - https://api.ratefox.io
- for all Ratefox API endpoints.
Ratefox API description in Swagger References - Click here.
Ratefox API Endpoints
Method | Endpoint | Description |
---|---|---|
POST | /hotels/ratefox | Finds a better price and books the hotel if successful. |
POST | /hotels/prefetch | Optimizes RateFox flow performance (Prefetch mode only). |
POST | /hotels/rebook | Launch Rebook monitoring for a booking created on client side |
Post Booking Requests | ||
POST | /hotels/cancel/{segmentId} | Cancels the RateFox segment reservation with the specified segmentId. Note: Only for Live mode |
POST | /hotels/checkstatus/{segmentId} | Checks the status of a RateFox segment reservation with the specified segmentId Note: Only for Live mode |
GET | /hotels/orderdata/{orderId} | Returns details of the RateFox booking with the specified orderId |
POST | /hotels/orders | Returns details of the RateFox bookings with the specified FromDate and ToDate |
POST | /hotels/excludefromrebooker/{orderId} | Exclude the Ratefox booking with specified orderID form Rebook monitoring |
✅ POST /hotels/ratefox
Standard Mode Ratefox API request for booking the specified hotel room at a better price.
Notes and Tips :
Special Parameters :
- Room Id:
Under the "Rooms" field, each "Id" - should be a unique (per reach room), self-generated GUID.- Passenger Id:
Under the "LeadPassenger" and "AdditionalPassengers" fields - each passenger "Id" should be unique (per reach passenger), self-generated GUID.- Allocation:
Under the "LeadPassenger" and "AdditionalPassengers" fields - each passenger's "Allocation" should be the respective room "Id" which was provided in the "Rooms" field.
Request Parameters
Field | Description | Format | Mandatory |
---|---|---|---|
SupplierHotel | object | Yes | |
SupplierId | Supplier’s ID in Ratefox. Integrated suppliers list https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers | Integer | Yes |
SupplierHotelId | Supplier’s HotelID - the corresponding supplier's Hotel key / Id, used to identify the desired property. | String | Yes |
CheckIn | Check-in date | String - Unix Epoch time | Yes |
CheckOut | Check-out date | String - Unix Epoch time | Yes |
Residency | The lead passenger residency. | String (2) ISO Country Code (Ex: US, CZ, IL) | Yes |
Price | object | Yes | |
BookingPrice | The price from client’s booking flow. Taxes, fees and commission from the request will be applied to the BookingPrice to obtain “clear” price for comparison with alternative packages’ prices. See examples below the table. - The Supplier Buying Price. | Double | Yes |
Currency | The currency of the BookingPrice. Rates in response will be in this currency. | String (3) ISO Currency Code (Ex: USD, EUR) | Yes |
TotalTax | object | ||
Amount | Amount of taxes | Double | Yes |
IsIncluded | Are taxes included in the BookingPrice. If false -excluded, BookingPrice will be increased by Tax Amount before comparing with alternative packages’ prices. When true does not affect. | Boolean | Yes |
Currency | If not provided, then Price Currency is used. | String (3) ISO Currency Code | |
TotalFee | object | ||
Amount | Amount of fees | Double | Yes |
IsIncluded | Are fees included in the BookingPrice. If true - included, BookingPrice will be reduced by Fee Amount before comparing with alternative packages’ prices. When false does not affect. | Boolean | Yes |
Currency | If not provided, then Price Currency is used | String (3) ISO Currency Code | |
Commission | object | ||
Amount | Amount of client’s commission. BookingPrice will be reduced by Commission Amount before comparing with alternative packages’ prices. | Double | Yes |
Currency | If not provided, then Price Currency is used | String (3) ISO Currency Codes | |
RefundableUntil | Refundability deadline. (If Non-Refundable, specify the same date of the request). | String Unix Epoch time | Yes |
Rooms | Array of objects. (Max. Rooms - 4) | Array | Yes |
Id | Room Id inside the request. Self-generated GUID. Should be a unique per each room in the array. | GUID | Yes |
RoomName | The name of the booked room in supplier terms Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc. (In any language) | String | Yes |
RoomBasis | The meal-plan, ”Board” (as it used by supplier from SupplierID). Examples: "Room Only", "Bed and Breakfast", "Half Board", "Full Board", "All Inclusive". | String | Yes |
AdultsCount | Number of adults in the room. (Max. Adults - 8). | Integer | Yes |
KidsAges | Array of kids ages. Each value must be between 0 and 17. If empty, there are no kids in the room. | Array of integer | |
WorkMode | Defines the WorkMode for the request. Possible values: “live”. Can be used only by the client which is set “live” in Gimmonix. The request in this mode produces the real booking; “evaluation”. The mode for testing and evaluation. The request in this mode doesn’t produce the real booking but full description of Ratefox found alternative is steal returned. This mode can be used by both clients connected to Ratefox as "evaluation" (new clients before the certification stage is completed) and those who are set "live". More about evaluation mode - link . | String | Yes |
LeadPassenger | Object. The main passenger from the booking | Yes | |
Id | Lead passenger’s Id inside the request. Self-generated GUID. Should be a unique per each passenger in the request. | GUID | Yes |
Allocation | The Allocation of the Pax from the RoomId/s from Rooms array. Identifies the room for the LeadPassenger. | GUID | Yes |
Name | object | Yes | |
GivenName | First name. Use English characters only, otherwise the booking might fail on the supplier side. | String(50) | Yes |
NamePrefix | Mr, Mrs, Ms etc. If not provided, “Mr” is used. | String | |
Surname | Last name. Use English characters only, otherwise the booking might fail on the supplier side. | String(50) | |
Type | Must be “adult” for the LeadPassenger | String | Yes |
Age | Lead passenger's age. | Integer | |
PhoneNumber | Passenger’s phone number to specify in the booking. | String(50) | |
CustomerEmail | Passenger’s email to specify in the booking. | String(254) | |
Address | object. Address details to specify in the booking | ||
CountryCode | The country code of the passenger. | String(2) ISO Country Code (Ex: US, CZ, IL) | |
AddressLine | The address of the passenger. | String(254) | |
StateProv | String(20) | ||
PostalCode | String(20) | ||
AdditionalPassengers | Array of objects. All passengers (adults and kids) except LeadPassenger must be described in this array. | Array | |
Id | Passenger’s Id inside the request. Self-generated GUID. Should be a unique per each passenger in the request | GUID | Yes |
Allocation | The Allocation of the Pax from the RoomId/s from Rooms array. Identifies the room for the AdditionalPassengers. | GUID | Yes |
Name | object | Yes | |
GivenName | First name. Use English characters only, otherwise the booking might fail on the supplier side. | String(50) | |
NamePrefix | Mr, Mrs, Ms etc. If not provided, “Mr” is used. | String | |
Surname | Last name. Use English characters only, otherwise the booking might fail on the supplier side. | String(50) | |
Type | “adult” or “child”. | String | Yes |
Age | Mandatory in case the passenger’s type is ”child”. The value must be between 0 and 17 and match one of the KigsAges array’s values. | Integer | |
LeadPaxRoomId | Id from Rooms array. Identifies the room of the LeadPassenger | GUID | Yes |
Language | Only “en” is currently supported | String | Yes |
RoomsRemarks | Free text remarks to be sent to the supplier within booking. Collection of "Key" : "Value” pairs, where Key is room Id from the Rooms array. Only suppliers that support this feature will receive the remarks. | ||
InternalAgentRef1 | Agent reference of the booking. | String | |
CustomBookingReference | Client reference. | String | |
PointOfSale | Defines the sales channel. Acceptable values must be agreed between the client and Ratefox. No predefined values are used. For more details - link . | String | |
SupplierIds | The list of suppliers by their IDs in Ratefox. If set then Ratefox only searches for better rates among the listed suppliers. Integrated suppliers list https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers | Array of Integer | |
ExcludeFromRebooker | Makes sense if client uses Rebook (adjusted by Ratefox team). Allows to switch off Rebook for created Ratefox booking | Boolean |
(*) Examples of price (P) calculations for comparison with alternative packages’ prices.
Ex.1 | Ex.2 | Ex.3 | Ex.3 | |
---|---|---|---|---|
BookingPrice | 500 | 500 | 500 | 500 |
TotalTax | ||||
Amount | 100 | 100 | 100 | 100 |
IsIncluded | true | false | true | false |
TotalFee | ||||
Amount | 50 | 50 | 50 | 50 |
IsIncluded | true | false | false | true |
Commission | ||||
Amount | 25 | 25 | 25 | 25 |
General formula:
P = BookingPrice - Commission.Amount + If(TotalTax.Included == True; 0; TotalTax.Amount) - If(TotalFee.Included == True; TotalFee.Amount; 0)
Ex.1: P = 500 - 50 - 25 = 425
Ex.2: P = 500 + 100 - 25 = 575
Ex.3: P = 500 - 25 = 475
Ex.4: P = 500 + 100 - 50 - 25 = 525
Response parameters
Field | Description | Format | Mandatory |
---|---|---|---|
Result | object. Filled in if Ratefox has made the booking | Yes | |
GimmonixHotelId | Ratefox internal Hotel Id. | Integer | Yes |
OrderId | Ratefox internal Order Id once a Booking is created. (Used to fetch bookings data in a separate post-booking request) | Integer | Yes |
SupplierName | Ratefox internal Supplier Name (The supplier from the booking was made by Ratefox) | String | |
ContractId | Id of the contract between Client and Supplier in Ratefox | Integer | Yes |
SupplierId | Supplier’s ID in Ratefox | Integer | Yes |
RequestPrice | The requested price. BookingPrice from the Request after applying Taxes, Fees and Commission (see request description above) - The Supplier Buying Price. | Double | Yes |
RequestPriceInClientCurrency | Request price in client currency | Double | Yes |
RequestedCurrency | The currency requested. | String ISO Currency Code | Yes |
ClientCurrency | The currency of client's account settings (adjusted by Ratefox team) | String ISO Currency Code | Yes |
FinalPrice | Final Price of the booking made by Ratefox. | Double | Yes |
FinalPriceInClientCurrency | Final Price of the booking in client currency | Double | Yes |
Revenue | [RequestPrice - FinalPrice] - the profit increase occurred by deducting the requested and final prices. | Double | Yes |
RevenueInClientCurrency | Revenue in client currency | Double | Yes |
IsProfitRequirementMet | Is returned if in client settings fallback to zero profit is allowed (adjusted by Ratefox team). True if Revenue is greater than threshold from client settings. False if Revenue is less than threshold from client settings (in this case booking is created without expected profit as a start point for Rebook). | Boolean | |
CustomBookingReference | The value from the request | String | |
Segments | Array of objects. Depending on the supplier multi-room booking may have one or several segments | Array | |
SegmentId | Ratefox Segment Id. (Used to cancel / Check-status in a separate post-booking request) | Integer | Yes |
Status | Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses. Note: in Evaluation mode Segment status is “EV” (successful Ratefox request doesn’t result real booking) | String | |
IsRebookCandidate | Is returned if in client settings Rebook is enabled (adjusted by Ratefox team). True if the segment is a candidate for rebooking (meets Rebook restrictions and in Ratefox request ExcludeFromRebooker = false). False if the segment won't be taken into account by Rebook. | Boolean | |
Rooms | Array of objects. | Array | |
RoomName | The name of the booked room. | String | |
MealPlan | The Basis / meal-plan of the booked room. | String | |
TotalPrice | object | ||
Commission | Commission amount | Double | Yes |
CommissionInSupplierCurrency | Commission amount in SupplierCurrency | Double | Yes |
Currency | Currency specified in the request in Price. | String ISO Currency Code | Yes |
FinalPrice | The final price of the booking in Currency | Double | Yes |
FinalPriceInSupplierCurrency | The price of the booking in Suppliers Currency | Double | Yes |
SupplierCurrency | The currency in which the price were originally received from the supplier. | String ISO Currency Code | |
TaxesAndFees | Array of objects | array | |
FeeTitle | the tax or fee title as returned by the supplier | String | |
IsIncludedInPrice | is this tax or fee included in the FinalPrice | Boolean | |
IsMandatory | is the tax or fee mandatory to be paid. For instance, 'resort fees' are typically mandatory, while 'wifi fee' might be not. | Boolean | |
Currency | Currency specified in the request in Price.Currency | String ISO Currency Code | |
UnitType | represents the category of the tax or fee: “Other” (not specified), “NotApplicable” (the supplier specified that this tax/fee is not applicable for the selected room), “NotSpecified”, “PerOccurrence” (of the fee title), “PerItem” (eg.: number of speedboats), “PerReservation” (the tax/fee will be applied per the entire reservation), “PerChild”, “PerAdult”, “PerNight”, “PerRoom”, “PerStay”, “PerPerson”. | String | |
FrequencyType | represents the repetitive type of tax or fee: “Other”, ”NotApplicable”, “NotSpecified”, “PerMinute”, “PerHour”, ”PerHalfDay”, “PerNight”, “PerWeek”, “PerStay”. | String | |
Value | the decimal value of the taxes and fees | String | |
IsValuePercentage | is the tax or fee a percentage value or an absolute value | Boolean | |
Remarks | the tax or fee description as the supplier returned | String | |
SupplierReservationDetails | object | ||
BookingID | Supplier’s booking confirmation Id | String | |
BookingReference | Supplier’s booking reference | String | |
BookingRemarks | Supplier’s booking remarks | String | |
SupplierVoucherId | Supplier’s voucher Id | String | |
PostBookingPriceChange | True if supplier changed the price (reduced or increased) while booking action was proceed. | Boolean | |
CancellationPolicies | Array of objects | Array | |
CancellationFee | Same approach to detail CancellationFee as for the TotalPrice object above | Yes | |
Commission | Double | Yes | |
CommissionInSupplierCurrency | Double | Yes | |
Currency | String ISO Currency Code | ||
FinalPrice | The charge amount in case of cancellation | Double | Yes |
FinalPriceInSupplierCurrency | The charge amount in case of cancellation in supplier currency | Double | Yes |
SupplierCurrency | String ISO Currency Code | ||
DateFrom | first date and time of the cancellation policy. Time is GMT. Please be aware that we won't be able to service complaints on a cancellation fee that was charged by the supplier because of time-zone differences between the supplier cancellation policy time to your time | String Unix Epoch time | Yes |
DateTo | end date and time for the policy. Time is GMT. | String Unix Epoch time | Yes |
Description | policy description as returned from the supplier. | String | |
Errors | Array of error codes and messages. | Array | |
Message | error description | String | |
ErrorCode | List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling | String | |
ErrorText | short error message | String |
Example Request
{
"SupplierHotel": {
"SupplierId": 1077,
"SupplierHotelId": "60055"
},
"CheckIn": "2025-03-20T09:36:37.099Z",
"CheckOut": "2025-03-21T09:36:37.099Z",
"Residency": "IL",
"Price": {
"BookingPrice": 261,
"Currency": "USD",
"TotalTax": {
"Amount": 10,
"IsIncluded": true,
"Currency": "USD"
},
"TotalFee": {
"Amount": 10,
"IsIncluded": false,
"Currency": "USD"
},
"Commission": {
"Amount": 100,
"Currency": "USD"
}
},
"RefundableUntil": "2025-02-25T09:36:37.099Z",
"Rooms": [
{
"AdultsCount": 2,
"Id": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"RoomBasis": "room only",
"RoomName": "Standard",
"KidsAges": [1]
}
],
"WorkMode": "Evaluation",
"LeadPassenger": {
"Id": "7e6f9032-fe51-4759-b88a-22c5c75a825e",
"Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"Name": {
"GivenName": "Aras",
"NamePrefix": "Mr",
"Surname": "Akkar"
},
"Type": "Adult"
},
"AdditionalPassengers": [
{
"Id": "0f741b1e-5e59-4fa9-ba61-84f5ecdd9988",
"Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"Name": {
"GivenName": "Nadu",
"NamePrefix": "Ms",
"Surname": "Akkar"
},
"Type": "Adult",
"Age": 21
},
{
"Id": "1f2c479a-354c-46a8-ade2-7b34927cadc6",
"Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"Name": {
"GivenName": "Kain",
"NamePrefix": "Mr",
"Surname": "Akkar"
},
"Type": "Child",
"Age": 1
}
],
"LeadPaxRoomId": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"Language": "en"
}
Example Response
{
"result": {
"gimmonixHotelId": 4137826,
"orderId": 3861446,
"supplierName": "HB2",
"contractId": 14821,
"supplierId": 1123,
"requestPrice": 161.0,
"requestedCurrency": "USD",
"finalPrice": 150.87,
"profit": 9.09,
"revenue": 10.129999999999999,
"segments": [
{
"segmentId": 3888217,
"status": "EV",
"totalPrice": {
"commission": 0.0,
"commissionInSupplierCurrency": 0.0,
"currency": "USD",
"finalPrice": 150.87,
"finalPriceInSupplierCurrency": 150.87,
"supplierCurrency": "USD",
"taxesAndFees": []
},
"supplierReservationDetails": {
"bookingID": null,
"bookingReference": null,
"bookingRemarks": " . Car park YES (With additional debit notes).Check-in hour 16:00-.",
"supplierVoucherId": null
},
"postBookingPriceChange": false,
"rooms": [
{
"roomName": "DOUBLE STANDARD",
"mealPlan": "ROOM ONLY"
}
],
"cancellationPolicies": [
{
"cancellationFee": {
"commission": 0.0,
"commissionInSupplierCurrency": 0.0,
"currency": "USD",
"finalPrice": 150.87,
"finalPriceInSupplierCurrency": 150.87,
"supplierCurrency": "USD"
},
"dateFrom": "2025-03-09T00:00:00",
"dateTo": "9999-12-31T00:00:00",
"description": null
}
]
}
]
},
"errors": []
}
Response Codes :
200
- OK403
- Forbidden.500
- Internal Server Error.
✅ POST /hotels/prefetch
Prefetch Mode Ratefox API request (pre-loading data, no booking is made). To proceed with the booking, a subsequent Ratefox API call is required.
Notes and Tips :
- The Prefetch Request will store room information for period of time specified in Client configurations.
- For the Ratefox API request to recognize the prefetch results, the information must be identical to the previous Prefetch request (including
Room Name
,Basis
,Cancellation Policy
,Check-in/out dates
,number of Adults
andKids
,Booking price
,Hotel
, etc.). Otherwise the Ratefox API request will proceed detached.
Request Parameters
Field | Description | Format | Mandatory |
---|---|---|---|
SupplierHotel | object | Yes | |
SupplierId | Supplier’s ID in Ratefox. Integrated suppliers list: https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers | Integer | Yes |
SupplierHotelId | Supplier’s HotelID - the corresponding supplier's Hotel key / Id, used to identify the desired property. | String | Yes |
CheckIn | Check-in date | String Unix Epoch time | Yes |
CheckOut | Check-out date | String Unix Epoch time | Yes |
Residency | The lead passenger residency | String(2) ISO Country Code (Ex: US, CZ, IL) | Yes |
Price | object | Yes | |
BookingPrice | The price from client’s booking flow. Taxes, fees and commission from the request will be applied to the BookingPrice to obtain “clear” price for comparison with alternative packages’ prices. See examples below the /hotels/ratefox endpoint request parameters table . - The Supplier Buying Price. | Double | Yes |
Currency | The currency of the BookingPrice. Rates in response will be in this currency | String(3) ISO Currency Code (Ex: USD, EUR) | Yes |
TotalTax | object | ||
Amount | Amount of taxes | Double | Yes |
IsIncluded | Are taxes included in the BookingPrice. If false - excluded, BookingPrice will be increased by Tax Amount before comparing with alternative packages’ prices. When true does not affect. | Boolean | Yes |
Currency | If not provided, then Price Currency is used | String(3) ISO Currency Code | |
TotalFee | object | ||
Amount | Amount of fees | Double | Yes |
IsIncluded | Are fees included in the BookingPrice. If true - included, BookingPrice will be reduced by Fee Amount before comparing with alternative packages’ prices. When false does not affect. | Boolean | Yes |
Currency | If not provided, then Price Currency is used | String(3) ISO Currency Code | |
Commission | object | ||
Amount | Amount of client’s commission. BookingPrice will be reduced by Commission Amount before comparing with alternative packages’ prices. | Double | Yes |
Currency | ISO Currency Codes. If not provided, then Price Currency is used | String(3) ISO Currency Codes | |
RefundableUntil | Refundability deadline | String Unix Epoch time | Yes |
Rooms | Array of objects. Possible room quantity is between 1 and 4 | Array | Yes |
Id | Room Id inside the request. Is generated by client GUID. Should be a unique per each room in the array | GUID | Yes |
RoomName | The name of the booked room in supplier terms. Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc. (In any language) | String | Yes |
RoomBasis | The meal-plan, ”Board” (as it used by supplier from SupplierID).Examples: "Room Only", "Bed and Breakfast", "Half Board", "Full Board", "All Inclusive". | String | Yes |
AdultsCount | Number of adults in the room. The value must be between 1 and 8 | Integer | Yes |
KidsAges | Array of kids ages. Each value must be between 0 and 17. If empty, there are no kids in the room | Array of integer | |
WorkMode | Defines the WorkMode for the request. Possible values: “live”. Can be used only by the client which is set “live” in Gimmonix. The request in this mode produces the real booking; “evaluation”. The mode for testing and evaluation. The request in this mode doesn’t produce the real booking but full description of Ratefox found alternative is steal returned. This mode can be used by both clients connected to Ratefox as "evaluation" (new clients before the certification stage is completed) and those who are set "live". More about evaluation mode - link . | String | Yes |
Language | Only “en” is currently supported | String | Yes |
PointOfSale | Defines the sales channel. Acceptable values must be agreed between the client and Ratefox. No predefined values are used. For more details - link . | String | |
SupplierIds | The list of suppliers by their IDs in Ratefox. If set then Ratefox only searches for better rates among the listed suppliers. Integrated suppliers list https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers | Array of Integer |
Example Request
{
"SupplierHotel": {
"SupplierId": 1077,
"SupplierHotelId": "60055"
},
"CheckIn": "2025-01-21T12:30:03.205Z",
"CheckOut": "2025-01-21T12:30:03.205Z",
"Residency": "IL",
"Price": {
"BookingPrice": 261,
"Currency": "USD",
"TotalTax": {
"Amount": 8,
"IsIncluded": true,
"Currency": "USD"
},
"TotalFee": {
"Amount": 6.2,
"IsIncluded": true,
"Currency": "USD"
},
"Commission": {
"Amount": 0,
"Currency": "USD"
}
},
"RefundableUntil": "2025-01-21T12:30:03.205Z",
"Rooms": [
{
"Id": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"RoomName": "Standard Room with See View",
"RoomBasis": "Bed and Breakfast",
"AdultsCount": 2,
"KidsAges": [
3
]
}
],
"Language": "en",
"WorkMode": "Evaluation"
}
Example Response
{
"result": {
"success": true
},
"errors": []
}
✅ POST /hotels/rebook
Launch Rebook monitoring for a booking created on a client side. Full booking description should be provided in the API request.
Terms of use:
By launching Rebook monitoring for a booking made directly with a supplier, the client agrees to the following: upon receiving a rebooking notification from Ratefox, the client is responsible for canceling their original booking.
This requirement applies only to the initial rebooking. For subsequent rebookings, Rebook will automatically cancel the previous booking (as it was initiated through Ratefox).
Note:
Rebook request parameters correspond to the same parameters of the Ratefox request.
Request Parameters
Field | Description | Format | Mandatory |
---|---|---|---|
SupplierHotel | object | Yes | |
SupplierId | Supplier’s ID in Ratefox. Integrated suppliers list https://documentation.hsp.gimmonix.com/docs/hsp-hotels-integrated-suppliers | Integer | Yes |
SupplierHotelId | Supplier’s HotelID - the corresponding supplier's Hotel key / Id, used to identify the desired property. | String | Yes |
CheckIn | Check-in date | String - Unix Epoch time | Yes |
CheckOut | Check-out date | String - Unix Epoch time | Yes |
Residency | The lead passenger residency. | String (2) ISO Country Code (Ex: US, CZ, IL) | Yes |
Price | object | Yes | |
BookingPrice | The price from client’s booking flow. Taxes, fees and commission from the request will be applied to the BookingPrice to obtain “clear” price for comparison with alternative packages’ prices. See examples below the table. - The Supplier Buying Price. | Double | Yes |
Currency | The currency of the BookingPrice. Rates in response will be in this currency. | String (3) ISO Currency Code (Ex: USD, EUR) | Yes |
TotalTax | object | ||
Amount | Amount of taxes | Double | Yes |
IsIncluded | Are taxes included in the BookingPrice. If false -excluded, BookingPrice will be increased by Tax Amount before comparing with alternative packages’ prices. When true does not affect. | Boolean | Yes |
Currency | If not provided, then Price Currency is used. | String (3) ISO Currency Code | |
TotalFee | object | ||
Amount | Amount of fees | Double | Yes |
IsIncluded | Are fees included in the BookingPrice. If true - included, BookingPrice will be reduced by Fee Amount before comparing with alternative packages’ prices. When false does not affect. | Boolean | Yes |
Currency | If not provided, then Price Currency is used | String (3) ISO Currency Code | |
Commission | object | ||
Amount | Amount of client’s commission. BookingPrice will be reduced by Commission Amount before comparing with alternative packages’ prices. | Double | Yes |
Currency | If not provided, then Price Currency is used | String (3) ISO Currency Codes | |
RefundableUntil | Refundability deadline. (If Non-Refundable, specify the same date of the request). | String Unix Epoch time | Yes |
Rooms | Array of objects. (Max. Rooms - 4) | Array | Yes |
Id | Room Id inside the request. Self-generated GUID. Should be a unique per each room in the array. | GUID | Yes |
RoomName | The name of the booked room in supplier terms Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc. (In any language) | String | Yes |
RoomBasis | The meal-plan, ”Board” (as it used by supplier from SupplierID). Examples: "Room Only", "Bed and Breakfast", "Half Board", "Full Board", "All Inclusive". | String | Yes |
AdultsCount | Number of adults in the room. (Max. Adults - 8). | Integer | Yes |
KidsAges | Array of kids ages. Each value must be between 0 and 17. If empty, there are no kids in the room. | Array of integer | |
WorkMode | should be "Evaluation" | String | |
LeadPassenger | Object. The main passenger from the booking | Yes | |
Id | Lead passenger’s Id inside the request. Self-generated GUID. Should be a unique per each passenger in the request. | GUID | Yes |
Allocation | The Allocation of the Pax from the RoomId/s from Rooms array. Identifies the room for the LeadPassenger. | GUID | Yes |
Name | object | Yes | |
GivenName | First name. Use English characters only, otherwise the booking might fail on the supplier side. | String(50) | Yes |
NamePrefix | Mr, Mrs, Ms etc. If not provided, “Mr” is used. | String | |
Surname | Last name. Use English characters only, otherwise the booking might fail on the supplier side. | String(50) | |
Type | Must be “adult” for the LeadPassenger | String | Yes |
Age | Lead passenger's age. | Integer | |
PhoneNumber | Passenger’s phone number to specify in the booking. | String(50) | |
CustomerEmail | Passenger’s email to specify in the booking. | String(254) | |
Address | object. Address details to specify in the booking | ||
CountryCode | The country code of the passenger. | String(2) ISO Country Code (Ex: US, CZ, IL) | |
AddressLine | The address of the passenger. | String(254) | |
StateProv | String(20) | ||
PostalCode | String(20) | ||
AdditionalPassengers | Array of objects. All passengers (adults and kids) except LeadPassenger must be described in this array. | Array | |
Id | Passenger’s Id inside the request. Self-generated GUID. Should be a unique per each passenger in the request | GUID | Yes |
Allocation | The Allocation of the Pax from the RoomId/s from Rooms array. Identifies the room for the AdditionalPassengers. | GUID | Yes |
Name | object | Yes | |
GivenName | First name. Use English characters only, otherwise the booking might fail on the supplier side. | String(50) | |
NamePrefix | Mr, Mrs, Ms etc. If not provided, “Mr” is used. | String | |
Surname | Last name. Use English characters only, otherwise the booking might fail on the supplier side. | String(50) | |
Type | “adult” or “child”. | String | Yes |
Age | Mandatory in case the passenger’s type is ”child”. The value must be between 0 and 17 and match one of the KigsAges array’s values. | Integer | |
LeadPaxRoomId | Id from Rooms array. Identifies the room of the LeadPassenger | GUID | Yes |
Language | Only “en” is currently supported | String | Yes |
RoomsRemarks | Free text remarks to be sent to the supplier within booking. Collection of "Key" : "Value” pairs, where Key is room Id from the Rooms array. Only suppliers that support this feature will receive the remarks. | ||
InternalAgentRef1 | Agent reference of the booking. | String | |
CustomBookingReference | Client reference. Should be unique for each client booking. | String | Yes |
Response parameters
Field | Description | Format | Mandatory |
---|---|---|---|
Result | object | ||
CustomBookingReference | as from request | String | Yes |
OrderId | Ratefox internal Order Id for a booking under Rebook monitoring. (Used to fetch current booking data and the history of rebookings in a separate post-booking OrderData request, to exclude the booking from Rebook monitoring in a separate post-booking Excludefromrebooker request) | String | Yes |
SegmentId | Ratefox Segment Id. (Used to cancel / check-status in a separate post-booking requests) | String | Yes |
Errors | Array of error codes and messages. | Array | |
Message | error description | String | |
ErrorCode | List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling | String | |
ErrorText | short error message | String |
Example Request
{
"SupplierHotel": {
"SupplierId": 1058,
"SupplierHotelId": "1032268"
},
"CheckIn": "2025-08-25T00:00:00.099Z",
"CheckOut": "2025-08-26T00:00:00.099Z",
"CustomBookingReference": "CR0108",
"Residency": "IL",
"Price": {
"BookingPrice": 180,
"Currency": "USD"
},
"RefundableUntil": "2025-08-01T00:00:00.099Z",
"Rooms": [
{
"AdultsCount": 2,
"Id": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"RoomBasis": "room only",
"RoomName": "Standard",
"KidsAges": []
}
],
"WorkMode": "Evaluation",
"LeadPassenger": {
"Id": "7e6f9032-fe51-4759-b88a-22c5c75a825e",
"Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"Name": {
"GivenName": "Adam",
"NamePrefix": "Mr",
"Surname": "Taros"
},
"Type": "Adult"
},
"AdditionalPassengers": [
{
"Id": "0f741b1e-5e59-4fa9-ba61-84f5ecdd9988",
"Allocation": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"Name": {
"GivenName": "Nadia",
"NamePrefix": "Ms",
"Surname": "Taros"
},
"Type": "Adult",
"Age": 21
}
],
"LeadPaxRoomId": "7e6f9032-fe51-4759-b88a-22c5c75a7070",
"Language": "en"
}
Example Response
{
"result": {
"customBookingReference": "CR0108",
"orderId": 3879909,
"segmentId": 3906741
},
"errors": []
}
Post Booking
✅ POST /hotels/cancel/{segmentId}
Cancel the Ratefox segment reservation with specified ID.
Since the cancellation request is also sent to the booking supplier, the Cancel endpoint only performs any actions for segments, created in "Live" work mode, and returns an error for segments created in "Evaluation" work mode.
Notes and Tips :
Multi-Room Reservations
- There are suppliers that return a single booking confirmation id for all rooms together - on Ratefox all rooms will be under single Segment ID.
- There are suppliers that return for each room a unique booking confirmation id - on Ratefox each room will have his own Segment ID (correlated with supplier).
'Cancel Book' request supports single Segment ID only.
For case (1): all rooms will be cancelled at once.
For case (2): requires to send a 'Cancel Book' request per each SegmentID. Or cancel part of the rooms by relevant SegmentIDs.
Request Parameters
segmentId
- Integer.
(ThesegmentId
is returned as part of Ratefox Response)
Response parameters
Field | Description | Format |
---|---|---|
BookCancelID | Cancellation ID | String |
CancellationComment | Cancellation Comment | String |
CancellationFee | Cancellation Fee | Double |
Currency | Currency of the cancellation fee | String ISO Currency Code |
Status | Cancellation Status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-cancellation-statuses | String |
Errors | Array of error codes and messages. | Array |
Message | error description | String |
ErrorCode | List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling | String |
ErrorText | short error message | String |
Example Request
curl --request POST \
--url https://example.com/hotels/cancel/454974 \
--header 'accept: application/json' \
--header 'authorization: Basic VGVzdFVzZXJOYW1lOmFzZGFkc2E='
Example Response
{
"Result": {
"BookCancelID": "string",
"CancellationComment": "string",
"CancellationFee": 0,
"Currency": "string",
"Status": "string"
},
"Errors": [
{
"Message": "string",
"ErrorCode": "string",
"ErrorText": "string"
}
]
}
✅ POST /hotels/checkstatus/{segmentId}
Check status of the Ratefox segment reservation with specified ID.
Since the status is checked with the booking supplier, the Checkstatus endpoint only performs any actions for segments, created in "Live" work mode, and returns an error for segments created in "Evaluation" work mode.
Request Parameters
segmentId
- Integer.
(ThesegmentId
is returned as part of Ratefox Response)
Response parameters
Field | Description | Format | Mandatory |
---|---|---|---|
Status | Segment Status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses | String | |
Errors | Array of error codes and messages. | Array | |
Message | error description | String | |
ErrorCode | List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling | String | |
ErrorText | short error message | String |
Example Request
curl --request POST \
--url https://example.com/hotels/checkstatus/454974 \
--header 'accept: application/json' \
--header 'authorization: Basic VGVzdFVzZXJOYW1lOmFzZGFkc2E='
Example Response
{
"Result": {
"Status": "OK"
},
"Errors": [
{
"Message": "string",
"ErrorCode": "string",
"ErrorText": "string"
}
]
}
✅ GET /hotels/orderdata/{orderId}
Provide description of the Ratefox order (booking) reservation with specified ID.
Request Parameters
orderid
- Integer.
(Theorderid
is returned as part of Ratefox Response)
Response parameters
Field | Description | Format | Mandatory |
---|---|---|---|
Result | object | ||
OrderId | Ratefox internal Id of the booking | Integer | Yes |
SupplierId | Supplier’s ID in Ratefox | Integer | Yes |
SupplierName | Ratefox internal Supplier Name (supplier from the booking made by Ratefox) | String | Yes |
HotelId | Ratefox Hotel Id | String | Yes |
ContractId | Id of the contract between Client and Supplier in Ratefox | Integer | Yes |
RequestPrice | BookingPrice from the Request after applying Taxes, Fees and Commission (see Ratefox API request description above) | Double | Yes |
RequestPriceInClientCurrency | Double | ||
RequestCurrency | Price.Currency from the request | String ISO Currency Code | Yes |
ClientCurrency | Client currency as set in client settings by Ratefox team. This currency is ones agreed between the client and the Ratefox and isn't changed after | String ISO Currency Code | Yes |
FinalPrice | Price from the booking made by Ratefox. If booking was rebooked by Rebook in live mode than Price of the last rebooking. | Double | Yes |
FinalPriceInClientCurrency | Double | ||
Revenue | Profit increase generated by the booking. If booking was rebooked by Rebook in live mode than Profit increase generated by the last rebooking. | Double | Yes |
RevenueInClientCurrency | Double | ||
TotalRevenue | Is returned if in client settings Rebook is enabled (adjusted by Ratefox team). If the booking was rebooked TotalRevenue contains total profit increase generated by Ratefox and Rebook. Only live rebookings are taken into account. | Double | |
TotalRevenueInClientCurrency | Double | ||
CheckIn | String Unix Epoch time | Yes | |
CheckOut | String Unix Epoch time | Yes | |
CustomBookingReference | The value from the Ratefox request | String | |
IsProfitRequirementMet | Is returned if Rebook is enabled for the client. True if initial booking created by Ratefox generated Revenue greater than threshold from client settings. False if Revenue was less than threshold from client settings (in this case booking was created without expected profit as a start point for Rebook). | Boolean | |
Segments | Array of objects | ||
SegmentId | Ratefox Segment Id | Integer | Yes |
Status | Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses. Note: in Evaluation mode Segment status is “EV” (successful Ratefox request doesn’t result real booking) | String | Yes |
IsRebookCandidate | Is returned if in client settings Rebook is enabled (adjusted by Ratefox team). True if the segment is a candidate for rebooking (meets Rebook restrictions and in Ratefox request ExcludeFromRebooker = false). False if the segment won't be taken into account by Rebook. | Boolean | |
Rooms | Array of objects | ||
RoomName | The name of the booked room in supplier terms. Examples: "Standard Room", "Double with sea view", "Triple", "Family Room", etc. | String | Yes |
MealPlan | The meal-plan name of the booked room in supplier terms | String | Yes |
TotalPrice | object | ||
Commission | Commission amount | Double | Yes |
CommissionInSupplierCurrency | Commission amount in SupplierCurrency | Double | Yes |
Currency | Currency specified in the request in Price.Currency | String ISO Currency Code | Yes |
FinalPrice | the price of the booking in Currency | Double | Yes |
FinalPriceInSupplierCurrency | the price of the booking in SupplierCurrency | Double | Yes |
SupplierCurrency | The currency in which the price were originally received from the supplier | String ISO Currency Code | |
TaxesAndFees | Array of objects | array | |
FeeTitle | the tax or fee title as returned by the supplier | String | |
IsIncludedInPrice | is this tax or fee included in the FinalPrice | Boolean | |
IsMandatory | is the tax or fee mandatory to be paid. | Boolean | |
Currency | Currency specified in the request in Price.Currency | String ISO Currency Code | |
UnitType | represents the category of the tax or fee: “Other” (not specified), “NotApplicable” (the supplier specified that this tax/fee is not applicable for the selected room), “NotSpecified”, “PerOccurrence” (of the fee title), “PerItem” (eg.: number of speedboats), “PerReservation” (the tax/fee will be applied per the entire reservation), “PerChild”, “PerAdult”, “PerNight”, “PerRoom”, “PerStay”, “PerPerson”. | String | |
FrequencyType | represents the repetitive type of tax or fee: “Other”, ”NotApplicable”, “NotSpecified”, “PerMinute”, “PerHour”, ”PerHalfDay”, “PerNight”, “PerWeek”, “PerStay”. | String | |
Value | the decimal value of the taxes and fees | String | |
IsValuePercentage | is the tax or fee a percentage value or an absolute value | Boolean | |
Remarks | the tax or fee description as the supplier returned | String | |
SupplierReservationDetails | object | ||
BookingID | Supplier’s booking confirmation Id | String | |
BookingReference | Supplier’s booking reference | String | |
BookingRemarks | Supplier’s booking remarks | String | |
SupplierVoucherId | Supplier’s voucher Id | String | |
CancellationPolicies | Array of objects | Array | |
CancellationFee | Double | Yes | |
CancellationFeeInSupplierCurrency | Double | Yes | |
Currency | String ISO Currency Code | ||
SupplierCurrency | String ISO Currency Code | ||
DateFrom | first date and time of the cancellation policy. Time is GMT. Please be aware that we won't be able to service complaints on a cancellation fee that was charged by the supplier because of time-zone differences between the supplier cancellation policy time to your time | String Unix Epoch time | Yes |
DateTo | end date and time for the policy. Time is GMT. | String Unix Epoch time | Yes |
Description | policy description as returned from the supplier. | String | |
History | Array of objects. Is returned if order's segment was rebooked and contains initial segment data and all rebookings data. | ||
ActionDate | Date and time of segment creation | String Unix Epoch time | Yes |
Status | Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses. | String | Yes |
Revenue | profit increase generated by this segment | Double | Yes |
RevenueInClientCurrency | revenue in client's currency | Double | Yes |
ContractId | Integer | ||
SupplierId | Integer | ||
SupplierName | String | ||
Rooms | object | ||
RoomName | String | ||
MealPlan | String | ||
TotalPrice | Double | ||
Commission | Double | ||
CommissionInSupplierCurrency | Double | ||
Currency | String ISO Currency Code | ||
FinalPrice | Double | ||
FinalPriceInSupplierCurrency | Double | ||
SupplierCurrency | String ISO Currency Code | ||
TaxesAndFees | array of objects | ||
FeeTitle | String | ||
IsIncludedInPrice | Boolean | ||
IsMandatory | Boolean | ||
Currency | String | ||
UnitType | String | ||
FrequencyType | String | ||
Value | String | ||
IsValuePercentage | Boolean | ||
Remarks | String | ||
SupplierReservationDetails | object | ||
BookingID | String | ||
BookingReference | String | ||
BookingRemarks | String | ||
SupplierVoucherId | String | ||
Initiator | service that created this segment. "Ratefox" - for segment created by Ratefox API request or by Rebook API request, "Rebooker" - for segment created by Rebook monitoring | String | Yes |
Errors | Array of error codes and messages. | ||
Message | error description | String | |
ErrorCode | List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling | String | |
ErrorText | Short error message | String |
Example Request
curl --request GET \
--url https://example.com/hotels/orderdata/456787 \
--header 'accept: application/json' \
--header 'authorization: Basic VGVzdFVzZXJOYW1lOmFzZGFkc2E='
Example Response
{
"Result": {
"HotelId": 0,
"OrderId": 0,
"SupplierName": "string",
"ContractId": 0,
"SupplierId": 0,
"RequestPrice": 0,
"RequestedCurrency": "string",
"FinalPrice": 0,
"Profit": 0,
"CheckIn": "2025-01-21T12:43:38.569Z",
"CheckOut": "2025-01-21T12:43:38.569Z",
"Segments": [
{
"SegmentId": 0,
"Status": "string",
"Rooms": [
{
"RoomName": "string",
"MealPlan": "string"
}
],
"TotalPrice": {
"Commission": 0,
"CommissionInSupplierCurrency": 0,
"Currency": "string",
"FinalPrice": 0,
"FinalPriceInSupplierCurrency": 0,
"SupplierCurrency": "string",
"TaxesAndFees": [
{
"FeeTitle": "string",
"IsIncludedInPrice": true,
"IsMandatory": true,
"Currency": "string",
"UnitType": "string",
"FrequencyType": "string",
"Value": "string",
"IsValuePercentage": true,
"Remarks": "string"
}
]
},
"SupplierReservationDetails": {
"BookingID": "string",
"BookingReference": "string",
"BookingRemarks": "string",
"SupplierVoucherId": "string"
},
"CancellationPolicies": [
{
"CancellationFee": 0,
"CancellationFeeInSupplierCurrency": 0,
"Currency": "string",
"SupplierCurrency": "string",
"DateFrom": "2025-01-21T12:43:38.569Z",
"DateTo": "2025-01-21T12:43:38.569Z",
"Description": "string"
}
]
}
]
}
}
✅ POST /hotels/orders
Provide the list of descriptions of the Ratefox orders (bookings) created in a specified period of time.
Request Parameters
Field | Description | Format | Mandatory |
---|---|---|---|
FromDate | Date and time of the beginning of the period | String Unix Epoch time | Yes |
ToDate | Date and time of the end of the period | String Unix Epoch time | Yes |
PageSize | The number of records returned in the response (from 1 to 100) | Integer | Yes |
PageNumber | Number of page to be returned. Numeration starts with 0. If not specified, then it is considered equal to 0 | Integer |
Response Parameters
Field | Description | Format | Mandatory |
---|---|---|---|
CurrentPage | Returned page number (same as PageNumber from the request). If PageNumber = 0 in the request CurrentPage isn't returned | Integer | |
TotalPages | Total number of pages | Integer | Yes |
TotalCount | Total number of orders that fit the requested period | Integer | Yes |
Orders | Array of objects | ||
OrderId | Ratefox internal Id of the booking | Integer | Yes |
SupplierId | Supplier’s ID in Ratefox | Integer | Yes |
SupplierName | Ratefox internal Supplier Name (supplier from the booking made by Ratefox) | String | Yes |
HotelId | Ratefox Hotel Id | String | Yes |
ContractId | Id of the contract between Client and Supplier in Ratefox | Integer | Yes |
RequestPrice | BookingPrice from the Request after applying Taxes, Fees and Commission (see Ratefox API request description above) | Double | Yes |
RequestPriceInClient Currency | Price from the request in clint currency | Double | Yes |
RequestCurrency | Price.Currency from the request | String ISO Currency Code | Yes |
ClientCurrency | Client currency as set in client settings by Ratefox team. This currency is ones agreed between the client and the Ratefox and isn't changed after | String ISO Currency Code | Yes |
FinalPrice | Price from the booking made by Ratefox | Double | Yes |
FinalPriceInClientCurrency | Price from the booking made by Ratefox in client currency | Double | Yes |
Revenue | RequestPrice - FinalPrice | Double | Yes |
RevenueInClientCurrency | Revenue in client currency | Double | Yes |
CheckIn | String Unix Epoch time | Yes | |
CheckOut | String Unix Epoch time | Yes | |
BookingDate | Order creation date | String Unix Epoch time | Yes |
CustomBookingReference | The value from the Ratefox request | String | |
IsProfitRequirementMet | Is returned if Rebook is enabled for the client. True if initial booking created by Ratefox generated Revenue greater than threshold from client settings. False if Revenue was less than threshold from client settings (in this case booking was created without expected profit as a start point for Rebook). | Boolean | |
Segments | Array of objects | ||
SegmentId | Ratefox Segment Id | Integer | Yes |
Status | Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses. Note: in Evaluation mode Segment status is “EV” (successful Ratefox request doesn’t result real booking) | String | Yes |
IsRebookCandidate | Is returned if in client settings Rebook is enabled (adjusted by Ratefox team). True if the segment is a candidate for rebooking (meets Rebook restrictions and in Ratefox request ExcludeFromRebooker = false). False if the segment won't be taken into account by Rebook. | Boolean | |
Rooms | Array of objects | ||
RoomName | The name of the booked room in supplier terms | String | Yes |
MealPlan | The meal-plan name of the booked room in supplier terms | String | Yes |
TotalPrice | object | ||
Commission | Commission amount | Double | Yes |
CommissionInSupplier Currency | Commission amount in SupplierCurrency | Double | Yes |
Currency | Currency specified in the request in Price.Currency | String ISO Currency Code | Yes |
FinalPrice | the price of the booking in Currency | Double | Yes |
FinalPriceInSupplier Currency | the price of the booking in SupplierCurrency | Double | Yes |
SupplierCurrency | The currency in which the price were originally received from the supplier | String ISO Currency Code | |
TaxesAndFees | Array of objects | array | |
FeeTitle | the tax or fee title as returned by the supplier | String | |
IsIncludedInPrice | is this tax or fee included in the FinalPrice | Boolean | |
IsMandatory | is the tax or fee mandatory to be paid. | Boolean | |
Currency | Currency specified in the request in Price.Currency | String ISO Currency Code | |
UnitType | represents the category of the tax or fee: “Other” (not specified), “NotApplicable” (the supplier specified that this tax/fee is not applicable for the selected room), “NotSpecified”, “PerOccurrence” (of the fee title), “PerItem” (eg.: number of speedboats), “PerReservation” (the tax/fee will be applied per the entire reservation), “PerChild”, “PerAdult”, “PerNight”, “PerRoom”, “PerStay”, “PerPerson”. | String | |
FrequencyType | represents the repetitive type of tax or fee: “Other”, ”NotApplicable”, “NotSpecified”, “PerMinute”, “PerHour”, ”PerHalfDay”, “PerNight”, “PerWeek”, “PerStay”. | String | |
Value | the decimal value of the taxes and fees | String | |
IsValuePercentage | is the tax or fee a percentage value or an absolute value | Boolean | |
Remarks | the tax or fee description as the supplier returned | String | |
SupplierReservationDetails | object | ||
BookingID | Supplier’s booking confirmation Id | String | |
BookingReference | Supplier’s booking reference | String | |
BookingRemarks | Supplier’s booking remarks | String | |
SupplierVoucherId | Supplier’s voucher Id | String | |
CancellationPolicies | Array of objects | Array | |
CancellationFee | Double | Yes | |
CancellationFeeInSupplier Currency | Double | Yes | |
Currency | String ISO Currency Code | ||
SupplierCurrency | String ISO Currency Code | ||
DateFrom | first date and time of the cancellation policy. Time is GMT. Please be aware that we won't be able to service complaints on a cancellation fee that was charged by the supplier because of time-zone differences between the supplier cancellation policy time to your time | String Unix Epoch time | Yes |
DateTo | end date and time for the policy. Time is GMT. | String Unix Epoch time | Yes |
Description | policy description as returned from the supplier. | String | |
History | Array of objects. Is returned if order's segment was rebooked and contains initial segment data and all rebookings data. | ||
ActionDate | Date and time of segment creation | String Unix Epoch time | Yes |
Status | Segment status. Possible statuses list: https://documentation.hsp.gimmonix.com/docs/orders-and-segments-statuses#segment-statuses. | String | Yes |
Revenue | profit increase generated by this segment | Double | Yes |
RevenueInClientCurrency | revenue in client's currency | Double | Yes |
ContractId | Integer | ||
SupplierId | Integer | ||
SupplierName | String | ||
Rooms | object | ||
RoomName | String | ||
MealPlan | String | ||
TotalPrice | Double | ||
Commission | Double | ||
CommissionInSupplierCurrency | Double | ||
Currency | String ISO Currency Code | ||
FinalPrice | Double | ||
FinalPriceInSupplierCurrency | Double | ||
SupplierCurrency | String ISO Currency Code | ||
TaxesAndFees | array of objects | ||
FeeTitle | String | ||
IsIncludedInPrice | Boolean | ||
IsMandatory | Boolean | ||
Currency | String | ||
UnitType | String | ||
FrequencyType | String | ||
Value | String | ||
IsValuePercentage | Boolean | ||
Remarks | String | ||
SupplierReservationDetails | object | ||
BookingID | String | ||
BookingReference | String | ||
BookingRemarks | String | ||
SupplierVoucherId | String | ||
Initiator | service that created this segment. "Ratefox" - for segment created by Ratefox API request or by Rebook API request, "Rebooker" - for segment created by Rebook monitoring | String | Yes |
Errors | Array of error codes and messages. | ||
Message | error description | String | |
ErrorCode | List of possible error codes with description https://documentation.hsp.gimmonix.com/docs/error-code-handling | String | |
ErrorText | Short error message | String |
Example Request
{
"FromDate": "2025-03-02T00:00:00.099Z",
"ToDate": "2025-03-02T23:59:59.999Z",
"PageSize": 3,
"PageNumber": 2
}
Example Response
{
"currentPage": 2,
"totalPages": 15,
"totalCount": 44,
"orders": [
{
"orderId": 3861622,
"supplierId": 1127,
"supplierName": "TLA",
"hotelId": 6846896,
"contractId": 4331,
"requestPriceInClientCurrency": 164.26,
"requestPrice": 164.26,
"requestedCurrency": "EUR",
"clientCurrency": "EUR",
"finalPrice": 161.95,
"finalPriceInClientCurrency": 161.95,
"revenueInClientCurrency": 2.31,
"revenue": 2.31,
"profit": 1.31,
"profitInClientCurrency": 1.31,
"checkIn": "2025-05-01T00:00:01.1",
"checkOut": "2025-05-02T00:00:01.1",
"bookingDate": "2025-03-02T10:01:39.733",
"segments": [
{
"segmentId": 3888394,
"status": "EV",
"rooms": [
{
"roomName": "Standard Double room (full double bed)",
"mealPlan": "Breakfast"
}
],
"cancellationPolicies": [
{
"cancellationFee": {
"currency": "EUR",
"finalPrice": 161.95,
"finalPriceInSupplierCurrency": 161.95,
"supplierCurrency": "EUR"
},
"dateFrom": "2025-04-26T00:00:00",
"dateTo": "9999-12-31T00:00:00",
"description": "\r\n"
}
],
"totalPrice": {
"currency": "EUR",
"finalPrice": 161.95,
"finalPriceInSupplierCurrency": 161.95,
"supplierCurrency": "EUR",
"taxesAndFees": []
},
"supplierReservationDetails": {
"bookingRemarks": "\r\n<p><b>Know Before You Go</b> <br /><ul> <li>This property offers transfers from the airport (surcharges may apply). Guests must contact the property with arrival details before travel, using the contact information on the booking confirmation. </li> </ul></p><p><b>Fees</b> <br /><p>The following fees and deposits are charged by the property at time of service, check-in, or check-out. </p> <ul> <li>Breakfast fee: EUR 10 for adults and EUR 10 for children (approximately)</li> <li>Airport shuttle fee: EUR 40 per vehicle (one way)</li> <li>Valet parking fee: EUR 25 per day</li> <li>Rollaway bed fee: EUR 40.0 per night</li> </ul> <p>The above list may not be comprehensive. Fees and deposits may not include tax and are subject to change. </p></p>\r\nBreakfast for children aged 0-0: 10 EUR\r\nExtra Bed: 40 EUR per guest per night.\r\nParking: 25 EUR per car per night."
}
}
]
},
{
"orderId": 3861623,
"supplierId": 1073,
"supplierName": "SUN",
"hotelId": 6846896,
"contractId": 4158,
"requestPriceInClientCurrency": 164.26,
"requestPrice": 164.26,
"requestedCurrency": "EUR",
"clientCurrency": "EUR",
"finalPrice": 155.61,
"finalPriceInClientCurrency": 155.61,
"revenueInClientCurrency": 8.65,
"revenue": 8.65,
"profit": 7.65,
"profitInClientCurrency": 7.65,
"checkIn": "2025-05-01T00:00:01.1",
"checkOut": "2025-05-02T00:00:01.1",
"bookingDate": "2025-03-02T10:01:56.077",
"segments": [
{
"segmentId": 3888395,
"status": "EV",
"rooms": [
{
"roomName": "Double room",
"mealPlan": "Breakfast"
}
],
"cancellationPolicies": [
{
"cancellationFee": {
"currency": "EUR",
"finalPrice": 155.61,
"finalPriceInSupplierCurrency": 162.0,
"supplierCurrency": "USD"
},
"dateFrom": "2025-04-25T00:00:00",
"dateTo": "9999-12-31T00:00:00"
}
],
"totalPrice": {
"currency": "EUR",
"finalPrice": 155.61,
"finalPriceInSupplierCurrency": 162.0,
"supplierCurrency": "USD",
"taxesAndFees": []
},
"supplierReservationDetails": {
"bookingRemarks": "\r\nFrom 5/1/2025 12:00:00 AM to 5/2/2025 12:00:00 AM: (CheckIn: 14:00, CheckOut: 12:00)\r\n"
}
}
]
},
{
"orderId": 3861624,
"supplierId": 1073,
"supplierName": "SUN",
"hotelId": 6846896,
"contractId": 4158,
"requestPriceInClientCurrency": 164.26,
"requestPrice": 164.26,
"requestedCurrency": "EUR",
"clientCurrency": "EUR",
"finalPrice": 155.61,
"finalPriceInClientCurrency": 155.61,
"revenueInClientCurrency": 8.65,
"revenue": 8.65,
"profit": 7.65,
"profitInClientCurrency": 7.65,
"checkIn": "2025-05-01T00:00:01.1",
"checkOut": "2025-05-02T00:00:01.1",
"bookingDate": "2025-03-02T10:02:33.847",
"segments": [
{
"segmentId": 3888396,
"status": "EV",
"rooms": [
{
"roomName": "Double room",
"mealPlan": "Breakfast"
}
],
"cancellationPolicies": [
{
"cancellationFee": {
"currency": "EUR",
"finalPrice": 155.61,
"finalPriceInSupplierCurrency": 162.0,
"supplierCurrency": "USD"
},
"dateFrom": "2025-04-25T00:00:00",
"dateTo": "9999-12-31T00:00:00"
}
],
"totalPrice": {
"currency": "EUR",
"finalPrice": 155.61,
"finalPriceInSupplierCurrency": 162.0,
"supplierCurrency": "USD",
"taxesAndFees": []
},
"supplierReservationDetails": {
"bookingRemarks": "\r\nFrom 5/1/2025 12:00:00 AM to 5/2/2025 12:00:00 AM: (CheckIn: 14:00, CheckOut: 12:00)\r\n"
}
}
]
}
],
"errors": []
}
✅ POST /hotels/excludefromrebooker/{orderId}
Exclude the Ratefox order (booking) with specified orderID from Rebook monitoring.
Request Parameters
ordertId
- Integer.
(TheorderId
is returned as part of Ratefox Response or Rebook Response)
Example Request
curl --request POST \
--url https://example.com/hotels/excludefromrebooker/3906695 \
--header 'accept: application/json' \
--header 'authorization: Basic VGVzdFVzZXJOYW1lOmFzZGFkc2E='
Example Response
{
"errors": [],
"success": true
}
🔗 Resources
- Hotel Identification: Each request requires a valid SupplierID and the corresponding supplier hotel key. To view the full list of suppliers and their IDs - Click here.
- Orders and Segments: Learn more about how orders and segments work, including possible statuses - Click here.
- Error Handling and Messages: For information on error codes, informative messages, and handling guidance - Click here.
✔️ Check-List for Starting the Evaluation / Integration
- Credentials for RateFox have been obtained.
- Access to Grafana - RateFox Monitoring and Insights tool has been granted.
- IP Whitelisting: When operating in Evaluation mode with a Live supplier, RateFox IPs must be whitelisted in the supplier's system.
📊 RateFox - Monitoring and Insights
For more information - Click here.
RateFox provides clients with visibility into their request flow, including a breakdown of Winning, Losing, and Invalid cases. This enables clients to better understand their integration, identify failure points, and ensure proper handling—ultimately helping them implement and optimize RateFox more effectively.
📞 Support & During and after Integration.
Our support team is committed to providing support for swift and effective integration, as well as ongoing assistance post-integration.
Should you need help, have questions, or seek clarification either during or after the integration process, you have two options for support:
- Search in our Documentation for the information you need. (Recommended)
- Submit a ticket to our dedicated support team.
Updated 1 day ago